Power-Programmierung

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

/ Power-Programmierung / CD2.mdf / c / library / dos / screen / scl120 / scl120.doc < prev next >

Wrap

Text File | 1994-06-12 | 432.8 KB | 15,911 lines

SCL1 C - FUNCTION LIBRARY VERSION 2.0 REFERENCE MANUAL COPYRIGHT (C) 1989,1990 BY: JOSE RODRIGUEZ ALVIRA AND JOSE R. LEBRON SCL1 Version 2.0 Reference Manual TABLE OF CONTENTS OVERVIEW . . . . . . . . . . . . . . . . . . . . . . . . . . 1 DISCLAIMER . . . . . . . . . . . . . . . . . . . . . . . . . 2 USING SCL1 . . . . . . . . . . . . . . . . . . . . . . . . . 3 WHAT IS SSG . . . . . . . . . . . . . . . . . . . . . . . . 3 SCL1DEMO . . . . . . . . . . . . . . . . . . . . . . . . . . 3 FUNCTION REFERENCE . . . . . . . . . . . . . . . . . . . . . 4 ALPHABETICAL REFERENCE . . . . . . . . . . . . . . . . . . . 5 AddExtension . . . . . . . . . . . . . . . . . . . . . 5 BackgroundOff . . . . . . . . . . . . . . . . . . . . . 6 BackgroundOn . . . . . . . . . . . . . . . . . . . . . 7 Beep . . . . . . . . . . . . . . . . . . . . . . . . . 8 BigCursor . . . . . . . . . . . . . . . . . . . . . . . 9 Bin2Ascii . . . . . . . . . . . . . . . . . . . . . . . 10 Box . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Buf2Disk . . . . . . . . . . . . . . . . . . . . . . . 13 Calendar . . . . . . . . . . . . . . . . . . . . . . . 14 Center . . . . . . . . . . . . . . . . . . . . . . . . 18 ChangeDumpColor . . . . . . . . . . . . . . . . . . . . 19 ChangeExtension . . . . . . . . . . . . . . . . . . . . 20 CheckBarMenu . . . . . . . . . . . . . . . . . . . . . 21 CheckChar . . . . . . . . . . . . . . . . . . . . . . . 23 CheckItemList . . . . . . . . . . . . . . . . . . . . . 24 CheckMouse . . . . . . . . . . . . . . . . . . . . . . 26 CheckMouseButton . . . . . . . . . . . . . . . . . . . 27 ClearKeyBuf . . . . . . . . . . . . . . . . . . . . . . 29 CloseFile . . . . . . . . . . . . . . . . . . . . . . . 30 Cls . . . . . . . . . . . . . . . . . . . . . . . . . . 31 CreateFile . . . . . . . . . . . . . . . . . . . . . . 32 CursorOff . . . . . . . . . . . . . . . . . . . . . . . 33 CursorOn . . . . . . . . . . . . . . . . . . . . . . . 33 DeleteFile . . . . . . . . . . . . . . . . . . . . . . 34 DialogBox . . . . . . . . . . . . . . . . . . . . . . . 35 DisableMouse . . . . . . . . . . . . . . . . . . . . . 36 DrawBarMenu . . . . . . . . . . . . . . . . . . . . . . 37 DrawBoxLine . . . . . . . . . . . . . . . . . . . . . . 39 DrawItemList . . . . . . . . . . . . . . . . . . . . . 40 DrawLine . . . . . . . . . . . . . . . . . . . . . . . 42 DrawMouseButton . . . . . . . . . . . . . . . . . . . . 43 ErrorBox . . . . . . . . . . . . . . . . . . . . . . . 45 ErrorShadowOff . . . . . . . . . . . . . . . . . . . . 47 ErrorShadowOn . . . . . . . . . . . . . . . . . . . . . 47 Page -i- SCL1 Version 2.0 Reference Manual TABLE OF CONTENTS FieldCheck . . . . . . . . . . . . . . . . . . . . . . 48 Fields . . . . . . . . . . . . . . . . . . . . . . . . 50 Fields2 . . . . . . . . . . . . . . . . . . . . . . . . 54 FileBox . . . . . . . . . . . . . . . . . . . . . . . . 62 FileBox2 . . . . . . . . . . . . . . . . . . . . . . . 63 File2Buf . . . . . . . . . . . . . . . . . . . . . . . 66 FillBlock . . . . . . . . . . . . . . . . . . . . . . . 68 FindFirst . . . . . . . . . . . . . . . . . . . . . . . 69 FindNext . . . . . . . . . . . . . . . . . . . . . . . 69 GetCurCol . . . . . . . . . . . . . . . . . . . . . . . 73 GetCurLine . . . . . . . . . . . . . . . . . . . . . . 73 GetCurrentDir . . . . . . . . . . . . . . . . . . . . . 74 GetCurSize . . . . . . . . . . . . . . . . . . . . . . 75 GetDate . . . . . . . . . . . . . . . . . . . . . . . . 76 GetDefaultDrive . . . . . . . . . . . . . . . . . . . . 78 GetDiskFreeSpace . . . . . . . . . . . . . . . . . . . 79 GetExtendedAscii . . . . . . . . . . . . . . . . . . . 80 GetFiles . . . . . . . . . . . . . . . . . . . . . . . 82 GetFileMode . . . . . . . . . . . . . . . . . . . . . . 83 GetFilePt . . . . . . . . . . . . . . . . . . . . . . . 85 GetFileSize . . . . . . . . . . . . . . . . . . . . . . 87 GetFreeMem . . . . . . . . . . . . . . . . . . . . . . 89 GetKey . . . . . . . . . . . . . . . . . . . . . . . . 90 GetString . . . . . . . . . . . . . . . . . . . . . . . 91 GetTime . . . . . . . . . . . . . . . . . . . . . . . . 93 GSSBox . . . . . . . . . . . . . . . . . . . . . . . . 94 HideMouse . . . . . . . . . . . . . . . . . . . . . . . 96 InitMouse . . . . . . . . . . . . . . . . . . . . . . . 97 InitUserError . . . . . . . . . . . . . . . . . . . . . 98 InitVideo . . . . . . . . . . . . . . . . . . . . . . . 100 KeyReady . . . . . . . . . . . . . . . . . . . . . . . 102 KeyStatus . . . . . . . . . . . . . . . . . . . . . . . 103 LineEditor . . . . . . . . . . . . . . . . . . . . . . 104 ListManager . . . . . . . . . . . . . . . . . . . . . . 111 ListWindow . . . . . . . . . . . . . . . . . . . . . . 113 MakeDir . . . . . . . . . . . . . . . . . . . . . . . . 120 Menu . . . . . . . . . . . . . . . . . . . . . . . . . 121 MenuSys . . . . . . . . . . . . . . . . . . . . . . . . 123 MenuSystem . . . . . . . . . . . . . . . . . . . . . . 128 MessageOff . . . . . . . . . . . . . . . . . . . . . . 138 MessageOn . . . . . . . . . . . . . . . . . . . . . . . 139 MessageShadowOff . . . . . . . . . . . . . . . . . . . 140 MessageShadowOn . . . . . . . . . . . . . . . . . . . . 140 MouseButton . . . . . . . . . . . . . . . . . . . . . . 141 MouseMenu . . . . . . . . . . . . . . . . . . . . . . . 145 MoveFilePt . . . . . . . . . . . . . . . . . . . . . . 148 MoveFilePt2Off . . . . . . . . . . . . . . . . . . . . 150 Page -ii- SCL1 Version 2.0 Reference Manual TABLE OF CONTENTS OpenFile . . . . . . . . . . . . . . . . . . . . . . . 152 PushCursor . . . . . . . . . . . . . . . . . . . . . . 154 PopCursor . . . . . . . . . . . . . . . . . . . . . . . 154 PopMenu . . . . . . . . . . . . . . . . . . . . . . . . 155 ReadFile . . . . . . . . . . . . . . . . . . . . . . . 157 RemoveDir . . . . . . . . . . . . . . . . . . . . . . . 158 RemoveExtension . . . . . . . . . . . . . . . . . . . . 159 RenameFile . . . . . . . . . . . . . . . . . . . . . . 160 ResetMouse . . . . . . . . . . . . . . . . . . . . . . 161 ResetMouseCur . . . . . . . . . . . . . . . . . . . . . 162 ScreenDump . . . . . . . . . . . . . . . . . . . . . . 163 ScrollDown . . . . . . . . . . . . . . . . . . . . . . 164 ScrollList . . . . . . . . . . . . . . . . . . . . . . 165 ScrollUp . . . . . . . . . . . . . . . . . . . . . . . 167 ScrollWindow . . . . . . . . . . . . . . . . . . . . . 168 Select . . . . . . . . . . . . . . . . . . . . . . . . 176 SetCurPos . . . . . . . . . . . . . . . . . . . . . . . 180 SetCurSize . . . . . . . . . . . . . . . . . . . . . . 181 SetDialogColor . . . . . . . . . . . . . . . . . . . . 182 SetErrorBoxColor . . . . . . . . . . . . . . . . . . . 183 SetFileMode . . . . . . . . . . . . . . . . . . . . . . 184 SetHorLimit . . . . . . . . . . . . . . . . . . . . . . 186 SetInt24Color . . . . . . . . . . . . . . . . . . . . . 187 SetMouseCur . . . . . . . . . . . . . . . . . . . . . . 188 SetMouseIsr . . . . . . . . . . . . . . . . . . . . . . 189 SetMousePos . . . . . . . . . . . . . . . . . . . . . . 191 SetShadowColor . . . . . . . . . . . . . . . . . . . . 192 SetUserBox . . . . . . . . . . . . . . . . . . . . . . 193 SetUserBoxLine . . . . . . . . . . . . . . . . . . . . 195 SetVerLimit . . . . . . . . . . . . . . . . . . . . . . 196 SetVideoMode . . . . . . . . . . . . . . . . . . . . . 197 SetVideoPage . . . . . . . . . . . . . . . . . . . . . 198 SetVideo4350 . . . . . . . . . . . . . . . . . . . . . 199 SetVideo25 . . . . . . . . . . . . . . . . . . . . . . 199 Shadow . . . . . . . . . . . . . . . . . . . . . . . . 200 ShowMouse . . . . . . . . . . . . . . . . . . . . . . . 201 SortPointers . . . . . . . . . . . . . . . . . . . . . 202 Sound . . . . . . . . . . . . . . . . . . . . . . . . . 203 SoundOff . . . . . . . . . . . . . . . . . . . . . . . 204 SoundOn . . . . . . . . . . . . . . . . . . . . . . . . 204 StopWatch . . . . . . . . . . . . . . . . . . . . . . . 205 TagItem . . . . . . . . . . . . . . . . . . . . . . . . 206 TagList . . . . . . . . . . . . . . . . . . . . . . . . 209 TagList2 . . . . . . . . . . . . . . . . . . . . . . . 211 TagMenu . . . . . . . . . . . . . . . . . . . . . . . . 215 Textwindow . . . . . . . . . . . . . . . . . . . . . . 218 TrapInt23 . . . . . . . . . . . . . . . . . . . . . . . 222 Page -iii- SCL1 Version 2.0 Reference Manual TABLE OF CONTENTS TrapInt24 . . . . . . . . . . . . . . . . . . . . . . . 223 TSound . . . . . . . . . . . . . . . . . . . . . . . . 224 Video . . . . . . . . . . . . . . . . . . . . . . . . . 225 VideoConfig . . . . . . . . . . . . . . . . . . . . . . 226 WaitKeyMouse . . . . . . . . . . . . . . . . . . . . . 228 WaitTime . . . . . . . . . . . . . . . . . . . . . . . 228 WFileBox . . . . . . . . . . . . . . . . . . . . . . . 229 Window . . . . . . . . . . . . . . . . . . . . . . . . 232 WriteChar . . . . . . . . . . . . . . . . . . . . . . . 234 WriteFile . . . . . . . . . . . . . . . . . . . . . . . 235 WriteOffLen . . . . . . . . . . . . . . . . . . . . . . 236 WriteOffset . . . . . . . . . . . . . . . . . . . . . . 237 WriteScreen . . . . . . . . . . . . . . . . . . . . . . 238 WriteScreen . . . . . . . . . . . . . . . . . . . . . . 239 YesNo . . . . . . . . . . . . . . . . . . . . . . . . . 241 YesNoShadowOff . . . . . . . . . . . . . . . . . . . . 242 YesNoShadowOn . . . . . . . . . . . . . . . . . . . . . 242 APPENDIX "A" - FILE RELATED FUNCTIONS . . . . . . . . . . . 243 APPENDIX "B" - MOUSE FUNCTIONS . . . . . . . . . . . . . . . 246 APPENDIX "C" - SCREEN RELATED FUNCTIONS . . . . . . . . . . 248 APPENDIX "D" - SCL1 HEADER FILES . . . . . . . . . . . . . . 250 APPENDIX "E" - DIALOG TYPE FUNCTIONS . . . . . . . . . . . . 251 APPENDIX "F" - CHANGES IN SCL1 VERSION 2.0 . . . . . . . . . 262 REGISTRATION INFORMATION . . . . . . . . . . . . . . . . . . 265 Page -iv- SCL1 Version 2.0 Reference Manual OVERVIEW The functions included here provide an alternative to the standard C-library functions. Extensive screen handling and mouse handling functions are provided that are not found in the standard library. Every effort has been made to exploit the PC hardware to its maximum capacity, portability has not been a primary goal. The library is designed to work with the Microsoft and the Borland Turbo-C C Compilers. The Shareware version contains stand alone small memory model libraries for both compilers. You do not need to understand the internal workings of the functions in order to take full advantage of them, all you need to know is how to call them and how to pass the required parameters. SCL1 is distributed under the Shareware concept. Feel free to try it, if you like and use the product please register your copy. Upon registration you will receive the following: 1. The latest version of SCL1. 2. Library modules for the small, medium, compact and large and huge memory models for the compiler of your choice. 3. SSG, a screen editor and program generator for use with SCL1. (see the included SSG Reference Manual) 4. You will be notified of all updates, additions and revisions. Feel free to distribute the Shareware version of SCL1 for trial use by others on a private non-commercial basis. The only distribution conditions are: that the code must not be modified or altered, and that no fee (except the nominal cost of distribution) may be charged. Page -1- SCL1 Version 2.0 Reference Manual DISCLAIMER The functions included in this package are, to the best of our knowledge, original or use standard accepted algorithms. We make no claim that these functions are optimized or totally suited for commercial use. They have been thoroughly tested and, to the best of our knowledge, perform as this documentation describe. We cannot accept any responsibility for any problems which may occur through the use of these functions for any application. After examining this document or the demo files included, if you feel that this package is not suitable for your use, please do not use it. THIS SOFTWARE AND MANUAL ARE SOLD "AS IS" AND WITHOUT WARRANTIES AS TO PERFORMANCE OF MERCHANTABILITY OR ANY OTHER WARRANTIES WHETHER EXPRESSED OR IMPLIED. BECAUSE OF THE VARIOUS HARDWARE AND SOFTWARE ENVIRONMENTS INTO WHICH THIS PROGRAM MAY BE PUT, NO WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE IS OFFERED. GOOD DATA PROCESSING PROCEDURE DICTATES THAT ANY PROGRAM BE THOROUGHLY TESTED WITH NON-CRITICAL DATA BEFORE RELYING ON IT. THE USER MUST ASSUME THE ENTIRE RISK OF USING THE PROGRAM. ANY LIABILITY OF THE SELLER WILL BE LIMITED EXCLUSIVELY TO PRODUCT REPLACEMENT OR REFUND OF PURCHASE PRICE. Feel free to send any comments or suggestions even if you do not decide to register your copy. If you find any bugs please let us know so that they can be traced and fixed. Please include with your comments any relevant information, such as; hardware configuration, description of the bug or problem and if possible a section of the problem code. Currently we can only support this program by mail. INSTALLING SCL1 All the files that are required to install SCL1 are distributed in a compressed self extracting form. You can use the included INSTALL.EXE program to perform the installation or you can manually decompress and copy them to the corresponding drives or directories. If you are using Microsoft C or Quick C copy the library files starting with M to the drive or directory where you have all your library files and the header file to the drive or directory where you have your include files. If you are using Turbo C use the files starting with T instead. The library files for the different memory models are identified with the last letter. Page -2- SCL1 Version 2.0 Reference Manual USING SCL1 To use SCL1 make sure you include the preprocessor directive; #include <SCL1.H> in your program. Several other header files are included with the keys, colors and music notes definitions. WHAT IS SSG You can really take the most advantage of SCL1 with an auxiliary program called SSG. SSG is a full featured screen editor and program generator. It will provide the required tools for building program screens and menus. After you design your screen, you instruct SSG about the desired operations you want to perform, such as: saving the screen contents, making a window, clearing all or part of the screen, making a menu, etc. Then SSG will write the C code for the desired operations using the functions available in SCL1. You can merge the generated code into your program. SSG will help you in speeding the most time consuming tasks during programming. A demo of SSG and its complete documentation is included in the Shareware version of SCL1. Upon registration you will receive a full working copy of SSG. SCL1DEMO The program SCL1DEMO demonstrates some of the functions available. It was written using SCL1 with the help of SSG. The best way to discover about SCL1's features is to run this demo. To start the demo type SCL1DEMO at the DOS prompt. You can obtain the source code for the Demo program by calling TECH-BBS, see Appendix "F". Page -3- SCL1 Version 2.0 Reference Manual FUNCTION REFERENCE An alphabetical reference of all the functions is included in this documentation manual. The reference provide full a description of each function. A uniform format has been used in this reference. At the top right corner of each page the name of the function or functions discussed in that page are shown to let you quickly locate a desired function. The format used is as follows: Function Name Function: Function Name Purpose: A description of what the function does. Declaration: Function prototype. The parameters types are shown. All the function prototypes have been included in the header file SCL1.H so it is not necessary to declare them in your programs. Returns: What the function returns. Parameters: A description of the parameters, structures, arrays, buffers, etc. required by the function are explained. Messages: In the dialog type functions, messages are exchanged with the function. This section describe these messages. Example: A short example of the function usage. Page -4- SCL1 Version 2.0 Reference Manual ALPHABETICAL REFERENCE AddExtension Function: AddExtension Purpose: Adds an extension to a filename if the filename has no extension and does not end with a period. Declaration: char *AddExtension(char *Filename, char *Extension); Returns: The return value is a pointer to the filename buffer. Parameters: Filename - char pointer to filename. Extension - char pointer to string holding the extension. Example: #include <scl1.h> char Filename[13]="FILE"; main() { printf("%s\n",Filename); printf("%s\n",AddExtension(Filename,"C")); } See also ChangeExtension and RemoveExtension Page -5- SCL1 Version 2.0 Reference Manual BackgroundOff Function: BackgroundOff Purpose: Stops a function running in the background. Declaration: void BackgroundOff(void); Returns: Nothing Parameters: None Example: #include <slc1.h> main() { BackgroundOn(B_Function); . . BackgroundOff(); } Notes: It is very important to stop any background running function before returning to DOS. Failure to do so can result in a system crash. See also BackgroundOn. Page -6- SCL1 Version 2.0 Reference Manual BackgroundOn Function: BackgroundOn Purpose: Makes a function share microprocessor time with a main process (run in the background). Declaration: void BackgroundOn(int (*FAddress)()); Returns: Nothing Parameters: FAddress - Pointer to the function that will be set to run in the background. It will be called 18.2 times per second. Example: #include <slc1.h> main() { BackgroundOn(B_Function); . . BackgroundOff(); } Notes: Functions that run in the background mode must not perform disk or keyboard input/output or call any time or sound related function. You should avoid using any standard library function that calls DOS or that uses the stack heavily. SCL1's screen related functions (except GSSBox) and the standard library data manipulation functions are generally safe to use in background mode. Background functions are called 18.2 per second. Each time they are called they should do as little as possible and return control to the calling routine. If you are using a Microsoft compiler you might need to disable the compiler's stack checking option using the "#pragma check_stack(off)" directive. Page -7- SCL1 Version 2.0 Reference Manual Beep Function: Beep Purpose: Sends a beep tone to the console speaker. Declaration: void Beep(void); Returns: Nothing Parameters: None Example: #include <scl1.h> main() { Beep(); /* Sends a short beep to the console.*/ } See also SoundOn, SoundOff and TSound Page -8- SCL1 Version 2.0 Reference Manual BigCursor Function: BigCursor Purpose: Changes the cursor size to a block. Declaration: void BigCursor(void); Returns: Nothing Parameters: None Example: #include <scl1.h> main() { BigCursor(); /* Turns the cursor to a block. */ } See also SetCurSize, GetCurCol, GetCurLine. Page -9- SCL1 Version 2.0 Reference Manual Bin2Ascii Function: Bin2Ascii Purpose: Fills a buffer with the ASCII code of a long integer value, adding commas, (i.e. 12,345). The buffer must be big enough to hold all characters plus commas and a zero (for terminating the string). Declaration: char *Bin2Ascii(long Number,char * Buffer); Returns: The return value is a pointer to the buffer. Parameters: Number - number whose ASCII value is to be written into the buffer (long integer). Buffer - char pointer to the buffer to hold the ASCII string. Example: #include <scl1.h> #define WIDTH 7 main() { long l; char buffer[8]; int i; l=999999; Cls(7,CLS_ALL); for(i=0;i < 6;++i,l/=10) { WriteScreenLen(7,10,10,WIDTH,Bin2Ascii(l,buffer)); GetKey(); } } Page -10- SCL1 Version 2.0 Reference Manual Box Function: Box Purpose: Draws a box with one of 12 predefined types of frames. The row and column coordinates, color and frame type are specified. The minimum box size is 2 rows and 2 columns. The function does not perform bound checking, the box will spill out of the screen area if the coordinates are outside the screen range. The function draws only the box's frame and does not fill the box's interior. If you desire to fill the box area use the GSSBox function instead. If you want to draw a shadow effect, make sure to leave enough space outside the box area. You can define other types of frames using the SetUserBox function. Declaration: void Box(int Color,int FrameType, int UpperRow, int LeftCol, int LowerRow, int RightCol); Returns: Nothing Parameters: Color - color attribute for the prompt (integer). FrameType - frame type, an integer value from 0 to 11 as follows, box frame 12 selects a user defined frame: ╔═════════╗ ┌─────────┐ ╓─────────╖ ╒═════════╕ ╒════════╕ ║ FRAME 0 ║ │ FRAME 1 │ ║ FRAME 2 ║ │ FRAME 3 │ │ FRAME 4│ ╚═════════╝ └─────────┘ ╙─────────╜ ╘═════════╛ └────────┘ ▄▄▄▄▄▄▄▄▄▄ ░░░░░░░░░░░ ▒▒▒▒▒▒▒▒▒▒ ▓▓▓▓▓▓▓▓▓▓ FRAME 5 ▌ FRAME 6▐ ░ FRAME 7 ░ ▒FRAME 8 ▒ ▓FRAME 9 ▓ ▀▀▀▀▀▀▀▀▀▀ ░░░░░░░░░░░ ▒▒▒▒▒▒▒▒▒▒ ▓▓▓▓▓▓▓▓▓▓ ██████████ ********** █FRAME 10█ *FRAME 11* ██████████ ********** (Note: You will not be able to print the correct frame types if your printer does not support the IBM extended ASCII character set.) Page -11- SCL1 Version 2.0 Reference Manual Box UpperRow - upper row coordinate of the box (integer). LeftCol - left column coordinate of the box (integer). LowerRow - lower row coordinate of the box (integer). RightCol - right column coordinate of the box (integer). (Note: the home position is row 0, column 0.) Example: #include <scl1.h> #include <scl1clor.h> int Color1=WHITE_BLACK; main() { Box(Color1,6,2,18,16,67); /* Draws a box starting in line 2, column 16 and ending in line 18, column 67 with a small solid border.*/ } See also GSSBox, Shadow, SetShadowColor, SetUserFrame. Page -12- SCL1 Version 2.0 Reference Manual Buf2Disk Function: Buf2Disk Purpose: Saves a buffer to disk. Declaration: int Buf2Disk(char* Filename, char *Buffer, unsigned int Bytes); Returns: The return value is "0" if no error occurs or the DOS error code if an error occurs. (See Appendix "A", FILE FUNCTIONS, for more information). Parameters: Filename - filename (and path if needed) of file to write data to (char pointer). Buffer - buffer that holds the data to be written to disk (char pointer). Bytes - variable that holds the number of bytes to write (unsigned integer). Example: #include <scl1.h> char buffer[]="We'll write this data to disk and read it back.\n"; main() { int Error; unsigned int size; if(Error=Buf2Disk("FILE.1",buffer,sizeof(buffer))) { printf("Error writing file # %i\n",Error); exit(-1); } size=sizeof(buffer); memset(buffer,0,size); if(Error=File2Buf("FILE.1",buffer,&size)) printf("Error reading file # %i\n",Error); else printf("%s\n",buffer); } See also File2Buf and TrapInt24. Page -13- SCL1 Version 2.0 Reference Manual Calendar Function: Calendar Purpose: Displays a calendar for a given month and year. A day can be displayed in a different color. This function can display the calendar either in the english or spanish language. The calendar position can be set to anywhere within the screen. No bounds checking is made so it is important to carefully calculate the display position. This is a dialog type function. Messages are defined for initializing the calendar to the present system date and to browse through dates using the cursor keys. Declaration: int Calendar(Message, CData *cd); Returns: This is a dialog type function. See Appendix "E" for a description of the general operation of these functions. The return values are the messages described in the Messages section. Parameters: The calendar information is passed in a structure type CData as follows: typedef struct{ int NColor; int RColor; int Row; int Col; int FrameType; unsigned int *ExitKeys; int Lang; int Month; int Day; int Year; unsigned int EventInfo; }CData; where; NColor - normal color attributes for the calendar display (integer). RColor - reversed color attributes for displaying the selected day (integer). Page -14- SCL1 Version 2.0 Reference Manual Calendar Row - row position for the upper left corner of the calendar (integer). Col - column position for the upper left corner of the calendar (integer). FrameType - type of frame to be used to enclose the calendar, it can be any of the frame types that can be used with the Box or GSSBox functions (integer). ExitKeys - an array of keys that will exit the calendar function(unsigned integer). Lang - a flag to define the language to be used when displaying the calendar. To display the calendar in english set Lang to "0", to display the calendar in spanish set Lang to "1" (integer). Month - the month to be displayed (integer). Day - the day to be displayed (integer). Year - the year to be displayed (integer). EventInfo - variable that holds the key pressed when you exit the function or a non defined key is pressed (unsigned integer). Messages: The following messages can be sent to Calendar: C_INIT - initialize the CData structure to NULL and sets the following default values: NColor - set to white characters in a black background or the normal color defined by calling SetDialogColors. HColor - set to highlighted white characters in a black background or the highlight color defined by calling SetDialogColors. Page -15- SCL1 Version 2.0 Reference Manual Calendar Col - set to column "24" for 80 column displays or to column "12" for 40 column displays. These row positions have been selected to display the calendar in the middle of the screen. Row - set to row "5". Lang - set to display the calendar in english. Month - set to the current system's month. Day - set to the current system's day. Year - set to the current system's year. FrameType - set to frame type "0" (double line). ExitKeys - defined as ENTER, ESCAPE, TAB & SHIFTAB. C_DRAW - display the calendar with the current display parameters. C_ACTIVE - display the calendar with the current display parameters and let the user change the date data using the cursor movement keys as follows: Key action Up Arrow cursor one day up. Down Arrow cursor one day down. Left Arrow cursor one day to the left. Right Arrow cursor one day to the right. Page Up increment the month by one. Page Down decrement the month by one. + increment the year by one. - decrement the year by one. C_CHECK_MOUSE - asks the function if the mouse has been clicked while pointing the calendar area (while currently the mouse does not affect the Calendar's operation, this messages is necessary when using this function as a field in the Fields2 function). Page -16- SCL1 Version 2.0 Reference Manual Calendar C_SHADOW_ON - displays a shadow effect the next time the calendar is drawn. C_SHADOW_OFF - disables the shadow effect. C_RESET - when this message is sent the Day, Month and Year variables set to the system's date. If the exit keys have not been defined they are set to the default exit keys. The following messages can be returned by Calendar: C_OK - the action requested has been performed. C_EXIT_KEY - a key that has been defined as an exit key has been pressed. C_MOUSE_EVENT - the mouse has been clicked after pointing outside the area defined by the function. C_ILLEGAL_KEY - a key that has not been defined has been pressed. C_NEW_POSITION - this message is returned every time the month, year or day has been changed. C_MY_MOUSE - this message is returned in response to the C_CHECK_MOUSE message if the mouse has been pressed in the Calendar screen area. Example: #include <scl1.h> main() { int Mess; /* returned messages */ CData test; /* define test as type CData */ Calendar(C_INIT,&test); /* Initialize to defaults */ Calendar(C_SHADOW_ON,&test); /* Display with shadow effect*/ Calendar(C_DRAW,&test); /* Display the calendar */ do { /* loop until exit key */ Mess=Calendar(C_ACTIVE,&test); /* browse through the the calendar */ }while (Mess!=C_EXIT_KEY); } Page -17- SCL1 Version 2.0 Reference Manual Center Function: Center Purpose: Centers a string horizontally. Declaration: int Center(char *String); Returns: Returns the column position required for displaying the string centered in the screen. Parameters: String - pointer to the string to be centered (char). Example: #include <slc1.h> #include <scl1clor.h> int Color1=WHITE_BLACK; char Txt[10]="Main Menu"; main() { int Column; Column=Center(Txt); WriteString(Color1,1,Column,Txt); } or main() { WriteString(Color1,1,Center(Txt),Txt); } Page -18- SCL1 Version 2.0 Reference Manual ChangeDumpColor Function: ChangeDumpColor Purpose: Changes the color attributes of a ScreenDump array (See ScreenDump). Declaration: void ChangeDumpColor(int OldColor, int NewColor, char*Array); Returns: Nothing Parameters: OldColor - color value you want to change (integer). NewColor - new color you desire (integer). *Array - ScreenDump array (char pointer). Example: #include <scl1.h> char Array[]={'A',7,'B',0x70,\n,'C',0x70,'D',7,0}; main() { /* Each character is followed by its color attribute, a \n can be used to indicate end of lines and a "0" must be used to indicate the end of the array */ ScreenDump(10,10,Array); /* Write at line 10, column 10 */ GetKey(); ChangeDumpColor(0x70,7,Array); ScreenDump(10,10,Array); /* Write at line 10, column 10 */ /* Change all character attributes 0x17 to 7 */ } See also ScreenDump. Page -19- SCL1 Version 2.0 Reference Manual ChangeExtension Function: ChangeExtension Purpose: Changes a filename's extension or adds an extension if it does not has one. Declaration: char *ChangeExtension(char *Filename, char *Extension); Returns: The return value is a pointer to the filename buffer. Parameters: Filename - filename to change its extension (char pointer). Extension - new extension (char pointer). Example: #include <scl1.h> char Buffer[]="MYFILE.TXT"; main() { printf("%s\n",Buffer); ChangeExtension(Buffer,".BAK"); /* Change extension from ".TXT" to ".BAK"*/ printf("%s\n",Buffer); } See also AddExtension and RemoveExtension Page -20- SCL1 Version 2.0 Reference Manual CheckBarMenu Function: CheckBarMenu (OBSOLETE, use the MenuSystem function, this function will eventually be removed from future versions of SCL1.) Purpose: Determines the number of the item selected with the mouse in a bar menu. Declaration: int CheckBarMenu(int Number, struct BarMenu *bm); Returns: The return value is the Selection number ( > "1") or "0" if none has been selected. Parameters: The BarMenu information must be given as an array of structures as follows: struct BarMenu{ int StartCol,EndCol; char String[20]; }; where, StartCol - column position where to start displaying the menu item information (integer). EndCol - column position where to end displaying the menu item information (integer). String - menu item information (char pointer). The parameters passed to the function are: Number - number of menu options (integer). BarMenu - pointer to the BarMenu structure. Page -21- SCL1 Version 2.0 Reference Manual CheckBarMenu Example: #include <scl1.h> #include <scl1clor.h> /* Bar Menu structure */ struct BarMenu bm[]={ 2,8, /*Start and end of display*/ "Option1", /*Menu item information */ 15,21, /* Second menu option */ "Option2"}; main() { int Selection=0; if(CheckMouse()) InitMouse(IM_SHOW); else printf("No Mouse available\n"); DrawBarMenu(BLACK_WHITE,WHITE_BLACK,2,Selection,bm); while(Selection==0) { if((Selection=CheckBarMenu(2,bm))) /* Selection made? */ DrawBarMenu(BLACK_WHITE,WHITE_BLACK,2,Selection,bm); } } NOTE: Use DrawBarMenu to draw bar menus. Page -22- SCL1 Version 2.0 Reference Manual CheckChar Function: CheckChar Purpose: Checks for a valid keyboard character. Declaration: unsigned int CheckChar(unsigned int Character, unsigned int ControlCode); Returns: The return value is the character, if valid, or "0" if the character is not valid. Parameters: character - character to verify (unsigned integer). ControlCode - type of character to accept (unsigned integer). Control codes defined in SCL1.H: CC_ANY - accept any character. CC_LETTER - only letters. CC_DIGIT - only digits. CC_CAPITALIZE - capitalize. CC_REAL - accept real numbers. CC_FILESPEC - accept valid filename characters CC_ESPANOL - letters & accented characters used in the spanish language. CC_PUNCTUATION - accept (,;.+-* spaces,etc.) CC_PATH - accept valid filenames and pathnames characters. CC_SEARCH - accept all characters of CC_PATH and the "*" and "?" characters. CC_EXPONENTIAL - accept numbers in exponential form. Example: #include<scl1.h> #include<scl1keys.h> main() { unsigned int Key; Key=GetKey(); if (CheckChar(Key,CC_LETTER))>0) /* Character is valid */ else /* Character is invalid */ } Page -23- SCL1 Version 2.0 Reference Manual CheckItemList Function: CheckItemList Purpose: Checks if the mouse has been clicked at any item in an item list (see DrawItemList). Declaration: int CheckItemList(int Number, int ItemLength, struct ItemList *il); Returns: The return value is the number of the item selected with the mouse (>"1") or "0" if none has been selected. Parameters: The item list information must be given as an array of structures as follows: struct ItemList{ int Row,Col; char *String; }; where, Row - row position of the item (integer). Col - column position of the item (integer). String - char pointer to item text. The parameters passed to the function are: Number - number of items (integer). ItemLength - maximum length of items (integer). ItemList - pointer to the defined structure. Page -24- SCL1 Version 2.0 Reference Manual CheckItemList Example: #include <scl1.h> #include <scl1clor.h> struct ItemList il[]={ 10,10,"String 1", 10,30,"String 2", 10,50,"String 3", }; main() { int Selection=0; Cls(WHITE_BLACK,CLS_ALL); if(CheckMouse()) InitMouse(IM_SHOW); else printf("No Mouse available\n"); DrawItemList(WHITE_BLACK,BLACK_WHITE,3,Selection,il); while(Selection==0) { if(Selection=CheckItemList(3,8,il)) DrawItemList(WHITE_BLACK,BLACK_WHITE,3,Selection,il); } } NOTE: Use DrawItemList to draw an ItemList structure to the screen. See also ListManager to integrate mouse and keyboard. The Dialog type function ListWindow provides an alternative way to perform the same task. Page -25- SCL1 Version 2.0 Reference Manual CheckMouse Function: CheckMouse Purpose: Determines if a mouse is installed. Sets variable MSE_MouseFl to "1" if mouse is found. Declaration: int CheckMouse(void); Returns: The return value of "1" if the mouse is installed and "0" if no mouse is installed. Parameters: None Example: #include <scl1.h> main() { /* do we have a mouse? */ if(CheckMouse()) { /* Yes */ ResetMouse(); /* reset mouse */ SetMouseIsr(); /* initialize ISR */ ShowMouse(); /* cursor on */ } . . . ResetMouse(); /* reset mouse before exit */ } Page -26- SCL1 Version 2.0 Reference Manual CheckMouseButton Function: CheckMouseButton Purpose: Checks if the mouse has been clicked at any screen mouse button. Declaration: int CheckMouseButton(int Number, struct MouseButton *p); Returns: The return value is the number of the selected screen Mouse Button or "0" if none has been selected. Parameters: The Mouse Button information must be given in a structure as follows: struct MouseButton{ int Top,Left,Bottom,Right; int Row,Col; char String[20]; }; where, Top - upper line coordinate of the Mouse Button area (integer). Left - upper column coordinate of the Mouse Button area (integer). Bottom - right row coordinate of the Mouse Button area (integer). Right - right column coordinate of the Mouse Button area (integer). Row - row coordinate of the Mouse Button text (integer). Col - column coordinate of the Mouse Button text (integer). String - Mouse Button text (maximum of 19 characters.). Page -27- SCL1 Version 2.0 Reference Manual CheckMouseButton The parameters passed to the function are: Number - number of mouse buttons (integer). MouseButton - pointer to defined structure. Example: struct MouseButton mb[]={ 4,35,6,45, /* Box coordinates */ 5,38, /* String position */ "Yes", /* String */ 10,35,12,45, 11,39, "No", }; /* Call CheckMouseButton(Number of options, pointer to the structure). */ if((Selection=CheckMouseButton(2,mb))) /* Bigger than 1? */ { /* Selection was made */ switch(Selection) { case 1: . . case 2: . . See also DrawMouseButton to draw the buttons. Page -28- SCL1 Version 2.0 Reference Manual ClearKeyBuf Function: ClearKeyBuf Purpose: Clears keyboard buffer of any character or keystroke pending to be processed. Declaration: void ClearKeyBuf(void); Returns: Nothing. Parameters: None. Example: #include <slc1.h> main() { ClearKeyBuf(); } Page -29- SCL1 Version 2.0 Reference Manual CloseFile Function: CloseFile Purpose: Closes a file. Declaration: int CloseFile(int Handle); Returns: The return value is "0" if no error occurs or the DOS error code if an error occurs. (See Appendix "A", FILE FUNCTIONS, for more information). Parameters: Handle - Handle number is given by DOS when you create or open a file (integer). Example: #include <scl1.h> /* This is the source code of the Buf2Disk function */ Buf2Disk(char *Filename,char *Buffer,unsigned int Bytes) { int i,handle; if(i=CreateFile(Filename,&handle,F_ARCHIVE)) return(i); if(i=WriteFile(handle,Buffer,Bytes)) { if(i > 0) CloseFile(handle); return(i); } return(CloseFile(handle)); } Page -30- SCL1 Version 2.0 Reference Manual Cls Function: Cls Purpose: Clears a screen area. Declaration: void Cls(int Color,int UpperRow,int LeftCol, int BottomRow, int RightCol); Returns: Nothing Parameters: Color - color attribute of the area to be cleared (integer). UpperRow - upper row coordinate of the area to be cleared (integer). LeftCol - left column coordinate of the area to be cleared (integer). LowerRow - lower row coordinate of the area to be cleared. (integer). RightCol - right column coordinate of the area to be cleared.(integer). (Note: the top left position is 0, column 0.) Example: #include <scl1.h> #include <scl1clor.h> int Color1=WHITE_BLACK; main() { Cls(Color1,18,0,24,79); } or, main() { Cls(Color1,CLS_ALL); (CLS_ALL is defined in SCL1.H to clear the whole screen.) } Page -31- SCL1 Version 2.0 Reference Manual CreateFile Function: CreateFile Purpose: Creates a new file or truncates an existing file to zero. Declaration: int CreateFile(char *Filename,int *Handle, int Attrib); Returns: The return value is "0" if no error occurs or the DOS error code if an error occurs. (See Appendix "A", FILE FUNCTIONS, for more information). Parameters: Filename - char pointer to a valid filename. Handle - pointer to an integer variable that contains the file handle number given by DOS (integer). Attrib - type of file to create, Read only, hidden, etc. (integer). The following types has been defined in SCL1.H: F_READ_ONLY, F_HIDDEN, F_SYSTEM, F_VOLUME, F_DIRECTORY, F_ARCHIVE Example: #include <scl1.h> /* This is the source code of the Buf2Disk function */ Buf2Disk(char *Filename,char *Buffer,unsigned int Bytes) { int i,handle; if(i=CreateFile(Filename,&handle,F_ARCHIVE)) return(i); if(i=WriteFile(handle,Buffer,Bytes)) { if(i > 0) CloseFile(handle); return(i); } return(CloseFile(handle)); } Page -32- SCL1 Version 2.0 Reference Manual CursorOff CursorOn Function: CursorOff CursorOn Purpose: Turns the cursor off (cursor not visible), or on (cursor visible). Declaration: void CursorOff(void); void CursorOn(void); Returns: Nothing Parameters: None Example: #include <scl1.h> main() { CursorOff(); printf("Press any key to turm cursor on\n"); GetKey(); CursorOn(); } Page -33- SCL1 Version 2.0 Reference Manual DeleteFile Function: DeleteFile Purpose: Deletes a file. Declaration: int DeleteFile(char *Filename); Returns: The return value is "0" if no error occurs or the DOS error code if an error occurs. (See Appendix "A", FILE FUNCTIONS, for more information). Parameters: Filename - char pointer to a valid filename. Example: #include <slc1.h> main() { int RetCode; RetCode=DeleteFile("c:\\bin\\file.1"); /* Will delete file "FILE.1" stored in drive "C" and the "BIN" directory. Note the double backslashes between the elements of the pathname. */ } Page -34- SCL1 Version 2.0 Reference Manual DialogBox Function: DialogBox Purpose: Displays a dialog box for keyboard input. The box will be displayed at the screen's center. The function takes care or saving and restoring the screen contents of the display area. See the GetString function for the editing features. Declaration: int DialogBox(int BoxColor, char *Prompt, int InputColor, int MaxChar, unsigned int CharType, char *Buffer); Returns: The return value is the number of characters typed or "-1" if Esc is pressed. Parameters: BoxColor - color attributes of the dialog box (integer). Prompt - pointer to the dialog prompt (char). InputColor - color attributes of the input (integer). MaxChar - maximum number of characters to accept (integer). CharType - the type of characters to accept as defined in SCL1.H (refer to the CheckChar function) (unsigned integer). Buffer - pointer to the buffer to be used to store the information entered, it must be one digit larger than the field size (for the string termination null character). Example: #include <scl1.h> #include <scl1clor.h> int Color1=WHITE_BLACK+HIGHLIGHT; int Color2=BLACK_WHITE; char buffer[33] /* buffer to hold input, one character larger than MaxChar */ main() { DialogBox(Color1,"Filename",Color2,32,CC_FILESPEC,buffer); } Page -35- SCL1 Version 2.0 Reference Manual DisableMouse Function: DisableMouse Purpose: Removes interrupt service routine installed by SetMouseIsr Declaration: void DisableMouse(void); Returns: Nothing Parameters: None Example: #include <scl1.h> main() { if(CheckMouse(); { ResetMouse(); SetMouseIsr(); ShowMouse(); } . . . DisableMouse(); } Page -36- SCL1 Version 2.0 Reference Manual DrawBarMenu Function: DrawBarMenu (OBSOLETE, use the MenuSystem function, this function will eventually be removed from future versions of SCL1.) Purpose: Draws a Bar Menu to the screen's top line. Declaration: void DrawBarMenu(int NormalColor,int SelectedColor, int NumItems,int Selection,struct BarMenu* bm); Returns: Nothing Parameters: The Menu information must be given as an array of structures as follows: struct BarMenu{ int StartCol,EndCol; char String[20]; }; where, StartCol - column position of the start of the prompt (integer). EndCol - column position of the end of the prompt (integer). String - char pointer to prompt. The parameters passed to the function are: NColor - normal color attributes of menu (integer). RColor - reversed color attributes of menu (integer). NumItems - number of menu items (integer). Selection - default selection (integer). BarMenu - pointer to a previously defined BarMenu structure. Page -37- SCL1 Version 2.0 Reference Manual DrawBarMenu Example: #include <scl1.h> #include <scl1clor.h> /* Bar Menu structure */ struct BarMenu bm[]={ 2,8, /*Start and end of display*/ "Option1", /*Menu item information */ 15,21, /* Second menu option */ "Option2"}; main() { int Selection=0; if(CheckMouse()) InitMouse(IM_SHOW); else printf("No Mouse available\n"); DrawBarMenu(BLACK_WHITE,WHITE_BLACK,2,Selection,bm); while(Selection==0) { if((Selection=CheckBarMenu(2,bm))) /* Selection made? */ DrawBarMenu(BLACK_WHITE,WHITE_BLACK,2,Selection,bm); } } Page -38- SCL1 Version 2.0 Reference Manual DrawBoxLine Function: DrawBoxLine Purpose: Draws either vertical or horizontal lines inside a box with the proper end line characters. Declaration: void DrawBoxLine(int Color,int FrameType,int Row1, int Col1,int Row2,int Col2); Returns: Nothing Parameters: The parameters passed to the function are: Color - color attributes of the line to be drawn (integer). FrameType - type of frame used to draw the box (integer). Row1 - row position where the line starts (integer). Col1 - column position where the line starts (integer). Row2 - row position where the line ends (integer). Col2 - column position where the line ends (integer). Note: To draw horizontal lines both Row1 and Row2 must have the same value, for vertical lines both Col1 and Col2 must have the same value. Example: #include <scl1.h> #include <scl1clor.h> int Color1=WHITE_BLACK; main() { Box(Color1,0,0,0,24,79); /* Full screen box */ DrawBoxLine(Color1,0,5,0,5,79); /* Horizontal line in row 5*/ DrawBoxLine(Color1,0,5,39,24,39);/* Vertical line between rows 5 and 24 */ } See also Box, GSSBox, DrawLine Page -39- SCL1 Version 2.0 Reference Manual DrawItemList Function: DrawItemList Purpose: Draws a list of items (strings) to the screen and permits the user to browse through them. The selected item (>"0") is drawn in the color specified with SelectedColor. Declaration: void DrawItemList(int NormalColor, int SelectedColor, int Number, int Selection, Struct ItemList *il); Returns: Nothing Parameters: The ItemList information must be given as an array of structures as follows: struct ItemList{ int Row,Col; char *String; }; where, Row - row position of the item (integer). Col - column position of the item (integer). String - char pointer to item text. The parameters passed to the function are: NormalColor - color attributes for the normal display of items (integer). SelectedColor - color attributes for the display of the selected item (integer). Number - number of items to be displayed (integer). Selection - default selection to be displayed when entering the function (integer). ItemList - pointer to a previously defined ItemList structure. Page -40- SCL1 Version 2.0 Reference Manual DrawItemList Example: #include <scl1.h> #include <scl1clor.h> struct ItemList il[]={ 10,10,"String 1", 10,30,"String 2", 10,50,"String 3", }; main() { int Selection=0; Cls(WHITE_BLACK,CLS_ALL); if(CheckMouse()) InitMouse(IM_SHOW); else printf("No Mouse available\n"); DrawItemList(WHITE_BLACK,BLACK_WHITE,3,Selection,il); while(Selection==0) { if(Selection=CheckItemList(3,8,il)) DrawItemList(WHITE_BLACK,BLACK_WHITE,3,Selection,il); } } NOTE: The ScrollWindow and ListWindow functions provide alternatives to perform the same tasks. Page -41- SCL1 Version 2.0 Reference Manual DrawLine Function: DrawLine Purpose: Draws either vertical or horizontal lines. Declaration: void DrawLine(int Color, int Row, int Col, int Count, int Direction, int Character); Returns: Nothing Parameters: The parameters passed to the function are: Color - color attributes of the line to be drawn (integer). Row - row position where the line starts (integer). Col - column position where the line starts (integer). Count - number of line characters to be drawn (integer). Direction - direction to draw. Variables DL_HORIZONTAL and DL_VERTICAL has been defined in SCL1.H. Character - graphic character to use for line drawing (integer). Example: #include <scl1.h> #include <scl1clor.h> int Color1=WHITE_BLACK; main() { DrawLine(Color1,5,5,10,DL_HORIZONTAL,196); /* Horizontal line in row 5, between columns 5 and 15 */ DrawLine(Color1,5,5,14,DL_VERTICAL,179); /* Vertical line between rows 5 and 19, column 5 */ } Page -42- SCL1 Version 2.0 Reference Manual DrawMouseButton Function: DrawMouseButton Purpose: Draws one or more mouse buttons to the screen. The selected button is drawn in the specified color with a double line box. A mouse button consists of a text prompt inside a box. By clicking the mouse after pointing to the button you can select it. Declaration: void DrawMouseButton(int NormalColor, int SelectedColor,int Number, int Selection,struct MouseButton *p); Returns: Nothing. Parameters: The MouseButton information must be given as an array of structures as follows: struct MouseButton{ int Top,Left,Bottom,Right; int Row,Col; char String[20]; }; where, Top - upper row coordinate of the Mouse Button area (integer). Left - left column coordinate of the Mouse Button area (integer). Bottom - lower row coordinate of the Mouse Button area (integer). Right - right column coordinate of the Mouse Button area (integer). Row - row coordinate of the Mouse Button text (integer). Col - column coordinate of the Mouse Button text (integer). String - the Mouse Button text (maximum of 19 characters.). Page -43- SCL1 Version 2.0 Reference Manual DrawMouseButton The parameters passed to the function are: NormalColor - color attribute used when button is not selected (integer). SelectedColor - Color used for a selected button (integer). Number - Number of buttons in the structure (integer). Selection - Number of the selected button (0 for none) (integer). MouseButton - pointer to predefined structure. Examples: #include <scl1.h> #include <scl1clor.h> int Color1=WHITE_BLACK; int Color2=BLACK_WHITE; struct MouseButton mb[]={ 4,35,6,45, /* Box coordinates */ 5,38, /* String position */ "Yes", /* String */ 10,35,12,45, 11,39, "No", }; main() { DrawMouseButton(Color1,Color2,2,1,mb); } NOTE: The Dialogue type MouseButton function provides a more flexible way to perform the same task. See also CheckMouseButton. Page -44- SCL1 Version 2.0 Reference Manual ErrorBox Function: ErrorBox Purpose: Displays a box, centered in the screen, with an error message. Several standard error messages have been defined in the ErrorBox function. You can add your own error messages or modify the standard errors by using the InitUserError function. You can define the color attributes and a shadow effect for the error boxes using the ErrorShadowOff, ErrorShadowOn and SetErrorBoxColor functions. Declaration: void ErrorBox(int ErrNum); Returns: Nothing. Parameters: ErrNum - error number corresponding to the error message to be displayed (integer). The error numbers defined are: ERROR DESCRIPTION 2 File not found 3 Path not found 4 Not enough handles 5 Access denied 6 Invalid handle 7 Memory control blocks destroyed 8 Insufficient memory 9 Invalid memory block address 10 Invalid environment 15 Invalid drive 18 No files found 27 Sector not found 29 Write Error 30 Read Error 255 File too Big -1 DOS Critical Error Page -45- SCL1 Version 2.0 Reference Manual ErrorBox Example: #include <scl1.h> struct ErrorMess em[]={ 256,"Please type either Y for YES\nor N for NO", 0}; main() { int Key; InitUserError(em); printf("\nInstall printer driver? (Y/N)\n"); do { Key=toupper(getch()); if(Key != 'Y' && Key != 'N') ErrorBox(256); else break; }while(1); } See ErrorShadowOff, ErrorShadowOn, SetErrorBoxColor and InitUserError. Page -46- SCL1 Version 2.0 Reference Manual ErrorShadowOff ErrorShadowOn Function: ErrorShadowOff ErrorShadowOn Purpose: Enables or disables a shadow effect when using the ErrorBox function. All subsequent calls to the ErrorBox function will be displayed with (or without) a shadow effect. Declaration: void ErrorShadowOff(void); void ErrorShadowOn(void); Returns: Nothing. Parameters: None. Example: #include <scl1.h> main { ErrorShadowOn(); /* Turn on shadow effect on error boxes */ . . . ErrorShadowOff(); /* Turn off shadow effect on error boxes */ } See ErrorBox, InitUserError and SetErrorBoxColor. Page -47- SCL1 Version 2.0 Reference Manual FieldCheck Function: FieldCheck Purpose: This function is designed to be used with the Fields2 function. When using Fields2 you must specify a function (in the FData1 structure) to handle events. It receives messages from Fields2 and must act upon them returning messages telling wether the cursor should move to the next/previous field, stay at the same position or exit the function. This function can, at the same time, monitor the data that is being entered and display help or error messages, if necessary. The FieldCheck function has been designed to handle the most typical events that are likely to occur when using Fields2: TAB - Moves the cursor to the next field. SHIFT+TAB - Moves the cursor to the previous field. ESC - Exit Fields2. ENTER - Its action depends on the active field type. When LineEditor, TagItem or Select are active, pressing ENTER moves control to the next field. When ScrollWindow or ListWindow are active, pressing ENTER will selects the highlighted item. When MouseButton is active, it works as an exit key. MOUSE EVENTS - Handles all mouse events. It is recommended that you always use FieldCheck. Even if you need to define your own field checking function for data validation or other purposes, you can still call FieldCheck from your function so that you don't need to care about the handling the events just mentioned. Declaration: int FieldCheck(FData2 *p); Returns: The return value is a message. Please refer to the Fields2 function for details. Page -48- SCL1 Version 2.0 Reference Manual FieldCheck Parameters: The required parameter is a pointer to the FData2 structure of the field to be checked. Example: See the example of the Fields2 function. Page -49- SCL1 Version 2.0 Reference Manual Fields Function: Fields Purpose: Get keyboard input using fields. With this function you can make data entry screens very easily. You can move across the fields using the TAB, SHIFTTAB keys or the mouse. The exit key is defined when calling the function. You have the capability of calling a data validation function after finishing editing each field. You can also call a help function associated with each field, this permits context sensitive help. When you reach the maximum field length, as defined by the MaxChar parameter, the cursor jumps to the next field, thus for special field types, such as date fields, you can define three separate data entry fields for the month, day and year and make them look as one field. Declaration: int Fields(int NColor, int RColor, int NFields, struct InputFields *ifld, unsigned int ExitKey, unsigned int HelpKey); Returns: The returned value is "1" if a key defined as an exit key is pressed and "-1" if the ESC key is pressed. Parameters: The field information must be given in a structure as follows: struct InputFields{ int PromptLine; int PromptCol; char *Prompt; int FieldLine; int FieldCol; char *FieldBuffer; int MaxChar; int CharType; int (* Helpf)(struct InputFields *p); int (* CheckF)(struct InputFields *p); }; Page -50- SCL1 Version 2.0 Reference Manual Fields Where; InputFields - the structure tag. Promptline - row position where to display the prompt (integer). PromptCol - column position where to display the prompt (integer). Prompt - pointer to the field prompt to be displayed (char). FieldLine - row position where to display the field (integer). FieldCol - Column position where to display the field (integer). FieldBuffer - pointer to the buffer to be used to store the field, it must be one digit larger than the field size to include the string termination null character (char). MaxChar - length of the input field (integer). CharType - the mask of valid characters as described in function CheckChar (integer). Helpf - pointer to a help function. This function receives a pointer to the fields structure and must be user supplied since it is not defined in SCL1.H. CheckF - pointer to a field validation function. This function receives a pointer to the fields structure and must be user supplied since it is not defined in SCL1.H. The CheckF must return a value of "0" if the field fails the test or a value of "1" to accept the entry. Page -51- SCL1 Version 2.0 Reference Manual Fields The parameters required are: NColor - color attributes for the prompt display (integer). RColor - color attributes for the field display (integer). NFields - number of fields (integer). InputFields - pointer to the InputFields structure. ExitKey - key to be used to exit the fields screen (unsigned integer). HelpKey - key to be used for calling the help function (unsigned integer). Example: #include <scl1.h> #include <scl1keys.h> #include <scl1clor.h> int test(struct InputFields *p); int helpf(struct InputFields *p); char buffer1[29]; char buffer2[29]; char buffer3[29]; char buffer4[29]; char buffer5[13]; char buffer6[11]; char buffer7[11]; char buffer8[11]; char buffer9[9]; char buffer10[11]; Page -52- SCL1 Version 2.0 Reference Manual Fields struct InputFields data[]={ 4,3,"Name:",4,11,buffer1,28,CC_LETTER | CC_PUNCTUATION | CC_CAPITALIZE,helpf,test, 6,3,"Address:",6,11,buffer2,28,CC_ANY | CC_CAPITALIZE,helpf,test, 8,3,"City:",8,11,buffer3,28,CC_ANY | CC_CAPITALIZE,helpf,test, 10,3,"State:",10,11,buffer4,28,CC_LETTER | CC_PUNCTUATION | CC_CAPITALIZE,helpf,test, 12,3,"Zip:",12,11,buffer5,12,CC_DIGIT,helpf,test, 4,44,"Customer Number:",4,60,buffer6,10,CC_DIGIT,helpf,test, 6,44,"Amount Due: $",6,60,buffer7,10,CC_REAL,helpf,test, 8,44,"Credit Limit: $",8,60,buffer8,10,CC_REAL,helpf,test, 10,44,"Date:",10,49,buffer9,8,CC_ANY,helpf,test, 12,44,"Transaction Number:",12,64,buffer10,10,CC_REAL,helpf, test}; main() { Cls(WHITE_BLACK,CLS_ALL); Fields(WHITE_BLACK,BLACK_WHITE,10,data,F10,F1); } helpf(struct InputFields *p) { PushCursor(); CursorOff(); MessageOn(BLACK_WHITE,"This function would\ndisplay your help screens."); WaitTime(200); MessageOff(); PopCursor(); } test(struct InputFields *p) { PushCursor(); CursorOff(); MessageOn(BLACK_WHITE,"This function could perform\ndata validation each time\nthe cursor moves to a new field\nor the user chosses to exit."); WaitTime(300); MessageOff(); PopCursor(); return(1); } NOTE: The Fields2 function provides a more flexible way to perform the same task. Page -53- SCL1 Version 2.0 Reference Manual Fields2 Function: Fields2 Purpose: This function lets you integrate various dialog type functions to design very powerful data entry and dialog screens. This function is similar to Fields but is more flexible. Every field can have its unique help and validation function which you can create and customize to provide a very useful user interface. The screens can contain any of the following fields: Line Editor - a field to enter and edit text and numeric data. Scroll Window - a field that displays a window with a partial list of items and permits tagging or selecting one of them. Mouse Button - a field that consists of a single prompt and permits either to ignore it or activate it. Tag Item - a field that permits to tag one or various options. Select - a field with multiple items that permits user selection. List Window - a field similar to the Scroll Window but permits multiple items in each line. Calendar - a field that displays a calendar of a given date and permits the user to modify the date. User Defined - a field defined by the user. Declaration: FData2 *Fields2(int Message,FData1 *fd1, FData2 *fd2); Returns: This function integrates various dialog type functions. See Appendix "E" for a description of the general operation of these functions. The returned value is a pointer to the FData2 structure. Page -54- SCL1 Version 2.0 Reference Manual Fields2 Parameters: The field information is given as an array of structures type FData1 as follows, one structure element for each field: Type FData1 structure: typedef struct{ int FieldType; void *Structure1; void *Structure2; int (* CheckF)(); }FData1; where, FieldType - an integer structure element containing the type of function for each field defined as follows: LINE_EDITOR SCROLL_WINDOW MOUSE_BUTTON TAG_ITEM SELECT LIST_WINDOW CALENDAR USER DEFINED Structure1 - pointer to a structure that contains all the information required for the field. Structure2 - pointer to a second structure that contains the field information. Use "0" if the field type does not require a second structure. CheckF - pointer to a function that will be called every time an event occurs. This function is responsible for the program flow. It constantly receives messages from Fields2 and returns messages to Fields2 telling it what should be done. This allows you to have complete control of the behavior of Fields2, as well as to perform complex data validation, context-sensitive help, etc. SCL1 includes a default CheckF called FieldCheck, you should use this function even if you create your own CheckF. Please refer to FieldCheck for more information. Page -55- SCL1 Version 2.0 Reference Manual Fields2 Fields2 needs a secondary structure FData2. This structure is used for communication between Fields2, the CheckF and the calling program. Each time an event occurs the CheckF is called. By reading the FData2 Message element, the CheckF knows what has just happened. For example, the user could have pressed the TAB key to move to the next field, or he may have clicked the mouse while pointing at another field, or he may have just type a character. CheckF is responsible of telling Fields2 what should be done. Type FData2 structure: typedef struct{ int Message; unsigned int EventInfo; FData1 *Structure; int ActiveField; int FieldsNumber; }FData2; where, Message - the message that is transferred between one field and another (integer). EventInfo - information about the keys that have been pressed (unsigned integer). FData1 - pointer to the FData1 structure. ActiveField - structure element that keeps a record of the current field. An integer value starting with "0" for the first field. This structure element is used internally by the function (integer). FieldsNumber - structure element that holds the number of fields, used internally by the function (integer). Type structure FData3: typedef struct{ int EventInfo; int (* CheckF)(); }FData3; Page -56- SCL1 Version 2.0 Reference Manual Fields2 where, EventInfo - information about the last illegal or exit key that has been pressed (unsigned integer). CheckF - pointer to check function (integer). NOTE: The information stored in structure type FData3 is used to define the parameters for user defined fields, in most applications you can disregard it. Messages: The messages that can be sent to the Fields2 function are: F_INIT - initialize the Fields2 structures to NULL. F_DRAW - draw the Fields2 screen. F_ACTIVE - edit the Fields2 information. When the CheckF is called, after determining what should be done, it can send one the following messages back to Fields2: F_MOUSE_EVENT - internal message used to keep track of where the mouse has been clicked. F_POSITION_STAY - this message instructs Fields2 not to move to any other field. This message is useful when a validation function has been called and the field does not pass the validation check, to permit the user to edit its contents. F_POSITION_UP - move to the next field. F_POSITION_DOWN - move to the previous field. F_SET_POSITION - this message is used to move the cursor to a desired field. You must first set the ActiveField structure member to the desired field number and then return this message. F_EXIT - instructs Fields2 to exit. F_SET_POS_EXIT - exit after setting a predetermined position. Page -57- SCL1 Version 2.0 Reference Manual Fields2 F_DRAW_NR - draw the Fields2 display and do not reset the field values. When using the F_DRAW message, Fields2 resets all the fields to their starting position. F_CHECK_ALL - when a CheckF senses that the user wants to exit, it can send this message to Fields2. Fields2 will call each CheckF defined for each field. This is very useful if you have a data validation CheckF for each field. By returning this message you can be sure that the data in each field is valid since Fields2 will move to any field that do not pass the CheckF validation. If all Fields are valid this message will behave like an F_EXIT message. F_COLORS - all Dialog functions get the color values from their structures. If you have initialized these structures as static data and you need to change the color values you can send this message to Fields2. It will change the colors in each structure to those specified as additional parameters. The first value passed is the Normal Color and the second is the Reversed Color. Due to the function integrating purpose of Fields2, it does not return messages. Example: #include <scl1.h> #include <scl1keys.h> #include <scl1clor.h> int OurFieldCheck(FData2 *fd2); /* our CheckF prototype */ /* Colors are initialized for a color monitor */ int Color1=WHITE_BLUE; int Color2=BLACK_CYAN; int Color3=BROWN_BLACK+HIGHLIGHT; Page -58- SCL1 Version 2.0 Reference Manual Fields2 /* Our first field will be a Select type */ SData1 sd1[]={ /* This is Select's first structure */ 11,37,"YES", 11,47,"NO", 0}; /* Select's secondary structure: */ SData2 sd2={23,11,16,"Create backup files:",0,0,0,0}; char buffer[31]; /* Buffer for the data-entry field */ /* Our second field will be a LineEditor type */ /* This structure defined the LineEditor parameters */ LEData led={23,13,16,"Backup Directory:",112,13,34,30,30, CC_PATH+CC_CAPITALIZE, 0,0,buffer,0,0,0,2,1,0,0,0,0,0,0,0}; /* The next two fields will of the MouseButton type */ /* We must define two structures for the MouseButtons */ MBData mb1={23,112,15,28,15,33,15,28,"≡ OK ≡",0,0,0,0}; MBData mb2={23,112,15,42,15,51,15,42,"≡ CANCEL ≡",0,0,0,0}; /* This is the FData1 structure: */ FData1 fd1[]={ SELECT,sd1,&sd2,OurFieldCheck, LINE_EDITOR,&led,0,OurFieldCheck, MOUSE_BUTTON,&mb1,0,OurFieldCheck, MOUSE_BUTTON,&mb2,0,OurFieldCheck, 0}; main() { FData2 fd2; /* Fields2 secondary structure */ /* Verify the type of display and change colors if neccessary */ if(Video()==MONO) { Color1=WHITE_BLACK; Color2=BLACK_WHITE; Color3=BLACK_WHITE+HIGHLIGHT; } Page -59- SCL1 Version 2.0 Reference Manual Fields2 /* Clear the screen and draw a box */ Cls(Color1,10,13,16,66); Box(Color1,0,10,13,16,66); /* Call Fields2 with a F_INIT message */ Fields2(F_INIT,fd1,&fd2); /* Tell Fields2 to modify colors to new values */ Fields2(F_COLORS,fd1,&fd2,Color1,Color2); /* Draw fields */ Fields2(F_DRAW,fd1,&fd2); /* Activate, now our CheckF will be in control of program flow */ Fields2(F_ACTIVE,fd1,&fd2); /* Check the FData2 structure to see if the user presses ESCAPE or selects the CANCEL mouse button for exiting */ if(fd2.ActiveField==3 || fd2.EventInfo==ESC) exit(-1); /* CANCEL selected */ else exit(0); /* OK selected */ } /* This is the custom field check function */ int OurFieldCheck(FData2 *fd2) { int Mess; /* Let SCL1 FieldCheck function do most of the work */ Mess=FieldCheck(fd2); /* Our only job is to watch for the F1 help key. It will be reported by Fields2 with an ILLEGAL_KEY message in the FData2 structure element. The message and the key value will be stored in the EventInfo element */ if(fd2->Message == LE_ILLEGAL_KEY && fd2->EventInfo==F1) { /* F1 key pressed, save cursor status and turn it off */ PushCursor(); CursorOff(); Page -60- SCL1 Version 2.0 Reference Manual Fields2 /* fd2->ActiveField tells us the field number that is active, we will use it to display context sensitive help */ switch(fd2->ActiveField) { case 0: /* first field */ MessageOn(Color3,"Use arrow keys to select if you\n want to create backup files."); break; case 1: /* second field */ MessageOn(Color3,"Type Backup files directory."); break; case 2: /* third field */ MessageOn(Color3,"Press ENTER to validate\n your selection."); break; case 3: /* fourth field */ MessageOn(Color3,"Press ENTER or ESC to\n cancel your selection."); break; } Mess=F_POSITION_STAY; /* return the position stay message so that the cursor does not move */ WaitKeyMouse(); /* wait for a key */ MessageOff(); /* restore screen */ PopCursor(); /* restore cursor */ } return(Mess); /* Mess holds the message Fields2 will receive, a POSITION_STAY message or the message returned by FieldCheck */ } Page -61- SCL1 Version 2.0 Reference Manual FileBox Function: FileBox Purpose: Displays a box with the directory information for loading or selecting files. Fills a buffer with the selected file/path. The function accepts mouse input. Declaration: int FileBox(int NColor, int RColor,char *Buffer); Returns: The return value is "-1" if the operation is cancelled by the user by pressing ESC or selecting the cancel option. Parameters: NColor - color attributes for normal color display (integer). RColor - color attributes for reverse color display (integer). Buffer - char pointer to buffer to hold selected filename. The search string is placed in the buffer before calling the function. If an empty buffer is used (NO SEARCH STRING SPECIFIED), the function will place the default path and the "*.*" search string in the buffer. Example: #include <scl1.h> #include <scl1clor.h> int Color1=BLACK_WHITE; int Color2=WHITE_BLACK; char FileBuf[80]; /* Buffer big enough so that the directory information will fit */ main() { FileBox(Color1,Color2,FileBuf); WriteScreen(Color1,20,12,"You have Selected:"); WriteScreen(Color1,20,33,FileBuf); } See also FileBox2 and WFileBox Page -62- SCL1 Version 2.0 Reference Manual FileBox2 Function: FileBox2 Purpose: Displays a box with the directory information for loading or selecting files. Fills a buffer with the selected file/path. The function accepts mouse input. The function automatically senses the current video mode and adjusts the display accordingly. Declaration: int FileBox2(int Message, FBData *p) Returns: This is a dialog derived function. See Appendix "E" for a description of the general operation of these functions. The return values are the messages described in the Messages section. Parameters: The file box information is given in a structure type FBData as follows: Structure type FBData; typedef struct{ int NColor; int RColor; int UpperRow; int LeftCol; int LowerRow; int RightCol; char *Filename; int Attrib; }FBData; where, NColor - normal color for the file box display (integer). RColor - reversed color for the file box display (integer). UpperRow - upper row coordinate for the file box's display (integer). LeftCol - left column coordinate for the file box's display (integer). LowerRow - lower row coordinate for the file box's display (integer). Page -63- SCL1 Version 2.0 Reference Manual FileBox2 RightCol - right column coordinate for the file box's display (integer). Filename - pointer to buffer to hold the selected filename. The search string is placed in the buffer before calling the function. If an empty buffer is used (NO SEARCH STRING SPECIFIED), the function will place the default path and the "*.*" search string into the buffer. Attrib - file attributes as defined by the DOS. Please refer to Appendix "A", FILE FUNCTIONS, for more details (integer). Messages: The following messages can be sent to FileBox2: FB_INIT - initialize the FBData structure to NULL and set the following default values: NColor - set to white characters in a black background or the normal color defined by calling SetDialogColors. RColor - set to black characters in a white background or the reversed color defined by calling SetDialogColors. UpperRow - set to row "5". LeftCol - set to column "20" for 80 column displays or to column "0" for 40 column displays. LowerRow - set to row "19" for 25 row displays or to row "36" for 43 row displays. RightCol - set to column "39" for 40 column displays and "59" for 80 column displays. Attrib - files and sub-directories. FB_DRAW - draw the FileBox to the screen. Page -64- SCL1 Version 2.0 Reference Manual FileBox2 FB_ACTIVE - browse through the displayed filenames and permit a selection or to cancel the operation using the cursor movement keys as follows: Key action Up Arrow cursor one item up. Down Arrow cursor one item down. END cursor to end of file list. HOME cursor to beginning of list. Page Up cursor one screen up. Page Down cursor one screen down. FB_RESET - when this message is sent the filebox variables are reset to the default value. If the exit keys have not been defined they are set to the default exit keys. The following messages can be returned by FileBox2: FB_OK - the action requested has been performed and a file has been selected. FB_CANCEL - the operation has been cancelled. Example: #include <scl1.h> #include <scl1clor.H> char Buffer[80]; int Color1=WHITE_BLACK,Color2=BLACK_WHITE; main() { FBData fbd; FileBox2(FB_INIT,&fbd); /* initialize the FBData structure*/ fbd.NColor=Color1; /* change display colors */ fbd.RColor=Color2; fbd.Filename=Buffer; /* buffer to hold directory info */ fbd.Attrib=F_READ_ONLY+F_HIDDEN+F_SYSTEM+F_DIRECTORY; /* set files attributes */ FileBox2(FB_DRAW,&fbd); /* display FileBox */ FileBox2(FB_ACTIVE,&fbd); /* let user make a selection */ } See also FileBox and WfileBox. Page -65- SCL1 Version 2.0 Reference Manual File2Buf Function: File2Buf Purpose: Reads a file into a buffer. Declaration: int File2Buf(char* Filename, char* Buffer, unsigned int* MaxSize); Returns: The return value is "0" if no errors occurs. When errors occur the returned values are as follows: a value of "-1" indicates that a critical DOS error has occurred, a value of "255" indicates that the file is larger than the size specified with MaxSize, and the standard DOS error code for other errors. You must have called TrapInt24 before in order to trap critical errors. The number of bytes read are stored in MaxSize. Parameters: Filename - valid pathname of the file to be read (char). Buffer - buffer to hold the information (char). MaxSize - number of bytes to read (unsigned integer). Example: #include <scl1.h> char buffer[]="We'll write this data to disk and read it back.\n"; main() { int Error; unsigned int size; if(Error=Buf2Disk("FILE.1",buffer,sizeof(buffer))) { printf("Error writing file # %i\n",Error); exit(-1); } Page -66- SCL1 Version 2.0 Reference Manual File2Buf size=sizeof(buffer); memset(buffer,0,size); if(Error=File2Buf("FILE.1",buffer,&size)) printf("Error reading file # %i\n",Error); else printf("%s\n",buffer); } See also File2Buff and TrapInt24. Page -67- SCL1 Version 2.0 Reference Manual FillBlock Function: FillBlock Purpose: Fills a screen area, defined with the parameters passed to the function, with a given character. Declaration: void FillBlock(int Color, int UpperRow, int LeftCol, int LowerRow, int RightCol, int Character); Returns: Nothing Parameters: Color - color attribute for the display (integer). UpperRow - upper row coordinate of the display (integer). LeftCol - left column coordinate of the display (integer). LowerRow - lower row coordinate of the display (integer). RightCol - right column coordinate of the display (integer). Character - character to be used for filling the screen area. This can be any valid character (integer). (Note: the home position is row 0, column 0.) Example: #include <scl1.h> #include <scl1clor.h> int Color1=BLACK_WHITE; main() { FillBlock(Color1,2,2,20,40,178); /* Will fill the area between rows 2-10 and columns 20-40 with character 178. */ } Page -68- SCL1 Version 2.0 Reference Manual FindFirst FindNext Function: FindFirst FindNext Purpose: Searches a disk directory for the file that matches the specified search attributes using DOS system call 0x4e. After finding the first matching file you must use FindNext to get subsequent matching files. Declaration: int FindFirst(char *SearchString,struct FileData *Buffer,int SearchAtr); int FindNext(void); Returns: The return value is "0" if no error occurs or the DOS error code if an error occurs. (See Appendix "A", FILE FUNCTIONS, for more information). DOS error code "18" is returned when no more files are found. Parameters: SearchString - pointer to a string with the search mask to be used (for example C:\BIN\*.EXE). If a matching file is found the FileData structure is filled with the file information. FileData - pointer to a structure of type FileData defined in SCL1.H: struct FileData{ char reserved[21]; char attrib; struct FILETIME time; struct FILEDATE date; long size; char name[13]; }; where, reserved - is an area reserved by DOS for subsequent calls to FindNext (char). Page -69- SCL1 Version 2.0 Reference Manual FindFirst FindNext attrib - Identifies the type of file found. Can be one or more of the following constants defined in SCL1.H: (use an OR operation to add them) F_READ_ONLY F_HIDDEN F_SYSTEM F_VOLUME F_DIRECTORY F_ARCHIVE time - structure with bit-fields members that holds the time when the file was created or last updated. FILETIME structure is defined in SCL1.H: struct FILETIME{ unsigned int seconds:5; unsigned int minutes:6; unsigned int hours:5; }; where, seconds - integer value from "0" to "59". minutes - integer value from "0" to "59". hours - integer value from "0" to "24". date - structure with bit-fields members that holds the date when the file was created or last updated. FILEDATE structure is defined in SCL1.H: struct FILEDATE{ unsigned int day:5; unsigned int month:4; unsigned int year:7; }; where, year - integer value from "0" to "119", to get the real year add "80" to this value. month - integer value from "1" to "12". Page -70- SCL1 Version 2.0 Reference Manual FindFirst FindNext day - integer value from "1" to "31". size - File's size in bytes (long integer). name - File's name. SearchAtr - is the DOS file attribute of eligible files. The following attribute constants have been defined in SCL1.H: F_ARCHIVE - only archive files will be reported. F_DIRECTORY - archive and directories will be reported. F_READ_ONLY - archive and read-only files will be reported. F_HIDDEN - archive and hidden files will be reported. F_SYSTEM - archive and system files will be reported. F_VOLUME - ONLY the volume label is reported. NOTE: This functions sets the DTA (Disk Transfer Area) to point to the FileData structure. Is important that you do not modify the DTA between a call to FindFirst and FindNext. Example: #include <scl1.h> #define NO_MORE_FILES 18 static void printinfo(struct FileData *fd); main() { struct FileData fd; /* file info will be stored here */ int RetVal; RetVal=FindFirst("*.*",&fd,F_VOLUME); /* read volume label */ if(RetVal==NO_MORE_FILES) /* no more files? */ printf("\nVolume has no label\n\n"); else printf("\nVolume label: %s\n\n",fd.name); Page -71- SCL1 Version 2.0 Reference Manual FindFirst FindNext /* read other files. Subdirectories, hidden, system and archive files */ RetVal=FindFirst("*.*",&fd,F_DIRECTORY | F_SYSTEM | F_HIDDEN); /* Get filenames while no error is reported */ while(RetVal==0) { printinfo(&fd); /* print file information */ RetVal=FindNext(); /* get next file */ } } static void printinfo(struct FileData *fd) { printf("%-13s",fd->name); /* print file name */ /* if file is not a directory, print file size */ if(fd->attrib == F_DIRECTORY) printf(" <DIR>"); else printf("%7li",fd->size); /* print date and time */ printf(" %.2i-%.2i-%.2i %.2i:%.2i:%.2i\n",fd->date.month, fd->date.day,fd->date.year+80,fd->time.hours, fd->time.minutes, fd->time.seconds); } Page -72- SCL1 Version 2.0 Reference Manual GetCurCol GetCurLine Function: GetCurCol GetCurLine Purpose: Returns the current cursor position. Declaration: char GetCurCol(char); char GetCurLine(void); Returns: GetCurCol returns the column position and GetCurLine returns the row position. Parameters: None Example: #include <scl1.h> main() { int Line,Col; Col=GetCurCol(); Line=GetCurLine(); printf("Cursor position before writing this string: %i, %i\n",Line,Col); } Page -73- SCL1 Version 2.0 Reference Manual GetCurrentDir Function: GetCurrentDir Purpose: Returns an ASCII string holding the default drive and path. Declaration: int GetCurrentDir(char *PathBuffer); Returns: The return value is "0" if no error occurs or the DOS error code if an error occurs. (See Appendix "A", FILE FUNCTIONS, for more information). Parameters: PathBuffer - pointer to a buffer to hold the pathname and drive letter (char). Example: #include <slc1.h> main() { int RetCode; char Buffer[80]; RetCode=GetCurrentDir(Buffer); } Page -74- SCL1 Version 2.0 Reference Manual GetCurSize Function: GetCurSize Purpose: Saves the current cursor size in variable GCS_CursorSize and returns the current cursor size. Declaration: int GetCurSize(void); Returns: The return value is the current cursor size. Parameters: None Example: #include <scl1.h> main() { GetCurSize(); /* Save actual size */ BigCursor(); /* Change size */ SetCurSize(GCS_CursorSize); /* Restore previous size */ } Page -75- SCL1 Version 2.0 Reference Manual GetDate Function: GetDate Purpose: Gets the system date. Declaration: struct DateData * GetDate(void); Returns: The return value is a pointer to the DateData structure defined as follows: struct DateData{ int WeekDay; int MonthDay; int Month; int Year; }; where, WeekDay - day of the week in numerical format (0=sunday,etc.) (integer). MonthDay - day of the month (1 - 31) (integer). Month - month number (1 - 12) (integer). Year - year (1980 - 2099) (integer). Parameters: None Example: #include <scl1.h> #include <scl1clor.h> char *Day[]={"Sunday","Monday","Tuesday","Wednesday", "Thursday","Friday","Saturday"}; char *Month[]={"","January","February","March","April","May", "June","July","August","September","October", "November","December"}; Page -76- SCL1 Version 2.0 Reference Manual GetDate main() { struct DateData *p; p=GetDate(); /* p points to DateData structure: p->WeekDay = day of the week (0=Sunday), p->MonthDay = day (1-31), p->Month = month (1-12) p->Year = year (1980 - 2099). The month and day numbers reported by GetDate will be used as index to the week and months names arrays we have previously defined. Use printf to print this data */ printf("Today is %s, %s %d,%d",Day[p->WeekDay], Month[p->Month],p->MonthDay,p->Year); } Page -77- SCL1 Version 2.0 Reference Manual GetDefaultDrive Function: GetDefaultDrive Purpose: Gets the default disk drive. Declaration: int GetDefaultDrive(void); Returns: The return value indicates the default drive number, 0=A, 1=B, etc. Parameters: None Example: #include <slc1.h> main() { int Drive; Drive=GetDefaultDrive(); printf("The default drive is %c\n",'A'+Drive) } Page -78- SCL1 Version 2.0 Reference Manual GetDiskFreeSpace Function: GetDiskFreeSpace Purpose: Gets the selected disk drive's free space in bytes. Declaration: long GetDefaultDrive(int Drive); Returns: The number of bytes free in the selected drive, "-1" if TrapInt24 was initialized and a critical error occurs or "-2" if the drive number is illegal. Parameters: Drive - Drive number (integer): 0 = default 1 = A 2 = B, etc. Example: #include <slc1.h> main() { printf("Disk Free Space=%li\n",GetDiskFreeSpace(0)); } Page -79- SCL1 Version 2.0 Reference Manual GetExtendedAscii Function: GetExtendedAscii Purpose: Changes ALT+Key combination into Extended Ascii character according to 4 tables: Table 0 - Spanish characters. Table 1 - Other language characters. Table 2 - Graphic characters. Table 3 - Greek letters, math symbols. Declaration: unsigned int GetExtendedAscii(unsigned int Key); Returns: The Ascii Code, if found (<"255"), or original Scan+Ascii Code, if not found (>"255"). Table 0 is the default. To change table set variable GE_CharTable to desired table number. The tables have been defined as follows: Table 0 - ALT+ aeiouvnm12 áéíóúüñÑ¡¿ Table 1 - ALT+ 123456789 qwertyuiop asdfghjkl zxcvbnm âêîôû£₧ƒ¥ áéíóúÿçÇñÑ àèìòùÄÉÖÜ äëïöü¡¿ Table 2 - ALT+ 123456789 qwertyuiop asdfghjkl zxcvbnm ╔╗╚╝═║░▒▓ ╦╠╣╩╬█▄▌▐▀ ┌┐└┘─│°∙· ┬├┤┴┼«» Table 3 - ALT+ 123456789 qwertyui asdfghjkl zx αßΓπΣσµτΦ ΘΩδ∞φε∩≡ ±≥≤⌠⌡÷≈√ⁿ ² (Note: You will not be to print the correct characters if your printer does not support the IBM extended ASCII character set.) Parameters: Key - Scan and ASCII code of a key (unsigned integer). Page -80- SCL1 Version 2.0 Reference Manual GetExtendedAscii Example: #include <slc1.h> #include <scl1keys.h> main() { unsigned int key; do { printf("Press an ALT + Key combination..."); key=GetKey(); if((key=GetExtendenAscii(key)) < 255) { printf("%c\n",key); break; } else printf("\nThis key combination has not been defined, try again!\n:); }while(1); } Page -81- SCL1 Version 2.0 Reference Manual GetFiles Function: GetFiles Purpose: Searches for the files that match the specified search string and attributes. Sets global variable GF_FileNumber to the number of files found and initialize an array of pointers, GF_PointerBuf, which will point to the filenames. Declaration: int GetFiles(char *SearchString,int SearchAtr); Returns: The return value is "0" if no error occurs or the DOS error code if an error occurs. (See Appendix "A", FILE FUNCTIONS, for more information). Parameters: SearchString - char pointer to the desired search string. SearchAtr - variable that defines the desired search attributes (integer). Example: #include <scl1.h> main() { int i; if(i=GetFiles("*.*",F_ARCHIVE+F_DIRECTORY)) printf("GetFiles reports error number %i\n",i); else { for(i=0;i < GF_FileNumber;++i) printf("%s\n",GF_PointerBuf[i]); } } Page -82- SCL1 Version 2.0 Reference Manual GetFileMode Function: GetFileMode Purpose: Gets the selected file's attributes. Declaration: int GetFileMode(char *Filename,int *FMode); Returns: The return value is 0 if no error occur or the DOS error code if an error occur. (See Appendix "A", FILE FUNCTIONS, for more information). Parameters: Filename - pointer to the file's name. Fmode - variable that holds the file mode (integer). The following masks has been defined in SCL1.H: F_READ_ONLY, F_HIDDEN, F_SYSTEM, F_VOLUME, F_DIRECTORY, F_ARCHIVE Example: #include <scl1.h> char Filename[]="FILE.1"; main() { int handle; unsigned int FMode; if(CreateFile(Filename,&handle,F_ARCHIVE)) exit(-1); if(GetFileMode(Filename,&FMode)) exit(-1); PrintFMode(FMode); if(SetFileMode(Filename,F_READ_ONLY | F_SYSTEM | F_HIDDEN)) exit(-1); if(GetFileMode(Filename,&FMode)) exit(-1); PrintFMode(FMode); if(SetFileMode(Filename,F_ARCHIVE)) exit(-1); DeleteFile(Filename); } Page -83- SCL1 Version 2.0 Reference Manual GetFileMode PrintFMode(unsigned int FMode) { printf("\nFile attributtes:\n\n"); if(FMode & F_READ_ONLY) printf("\tRead Only\n"); if(FMode & F_HIDDEN) printf("\tHidden\n"); if(FMode & F_SYSTEM) printf("\tSystem\n"); if(FMode & F_ARCHIVE) printf("\tArchive\n"); } Page -84- SCL1 Version 2.0 Reference Manual GetFilePt Function: GetFilePt Purpose: Gets the file's pointer position. Declaration: long GetFilePt(int Handle); Returns: The file pointer position of the file whose handle is Handle. Returns "-1" when a critical error is detected. (See Appendix "A", FILE FUNCTIONS, for more information). Parameters: FHandle - Handle returned by DOS when you open or create a file (integer). Example: #include <scl1.h> #include <string.h> /* This example creates a file with several names in lower- case. We'll read this file one record at a time into our buffer and convert the string to uppercase before rewriting it back to disk. For simplicity, no error checking is shown in the example */ struct NAME_REC{ /* Our file format */ char Name[7]; }nr; /* nr will be used as a buffer for converting strings to uppercase */ /* This is the data of the file we will create */ struct NAME_REC names[]={ "John", "Mary", "Robert", "Ann"}; main() { int handle,i,j; long fileptr,records; Page -85- SCL1 Version 2.0 Reference Manual GetFilePt /* create file */ if(Buf2Disk("DEMO.FL",(char *)names,sizeof(names))) { printf("Error creating file\n"); exit(-1); } /* Open file for reading and writing */ OpenFile("DEMO.FL",&handle,DOS2_RW); /* number of records in file = file size / size of structure NAME_REC */ records=GetFileSize(handle)/sizeof(struct NAME_REC); /* read one record at a time while there are records */ for(;records > 0;--records) { /* save actual file pointer position */ fileptr=GetFilePt(handle); /* read data, file pointer is automatically moved to next record by DOS */ ReadFile(handle,(char *)&nr,sizeof(struct NAME_REC)); /* capitalize name */ strupr(nr.Name); /* move file pointer to original position */ MoveFilePt2Offset(handle,fileptr); /* write our data, pointer points again to next record */ WriteFile(handle,(char *)&nr,sizeof(struct NAME_REC)); } CloseFile(handle); system("type DEMO.FL"); } Page -86- SCL1 Version 2.0 Reference Manual GetFileSize Function: GetFileSize Purpose: Gets the size of the selected file. Declaration: long GetFileSize(int Handle); Returns: The size of the file whose handle is Handle. Returns "-1" when a critical error is detected. (See Appendix "A", FILE FUNCTIONS, for more information). Parameters: Handle - Handle returned by DOS when you open or create a file (integer). Example: #include <scl1.h> #include <string.h> /* This example creates a file with several names in lower- case. We'll read this file one record at a time into our buffer and convert the string to uppercase before rewriting it back to disk. For simplicity, no error checking is shown in the example */ struct NAME_REC{ /* Our file format */ char Name[7]; }nr; /* nr will be used as a buffer for converting strings to uppercase */ /* This is the data of the file we will create */ struct NAME_REC names[]={ "John", "Mary", "Robert", "Ann"}; main() { int handle,i,j; long fileptr,records; Page -87- SCL1 Version 2.0 Reference Manual GetFileSize /* create file */ if(Buf2Disk("DEMO.FL",(char *)names,sizeof(names))) { printf("Error creating file\n"); exit(-1); } /* Open file for reading and writing */ OpenFile("DEMO.FL",&handle,DOS2_RW); /* number of records in file = file size / size of structure NAME_REC */ records=GetFileSize(handle)/sizeof(struct NAME_REC); /* read one record at a time while there are records */ for(;records > 0;--records) { /* save actual file pointer position */ fileptr=GetFilePt(handle); /* read data, file pointer is automatically moved to next record by DOS */ ReadFile(handle,(char *)&nr,sizeof(struct NAME_REC)); /* capitalize name */ strupr(nr.Name); /* move file pointer to original position */ MoveFilePt2Offset(handle,fileptr); /* write our data, pointer points again to next record */ WriteFile(handle,(char *)&nr,sizeof(struct NAME_REC)); } CloseFile(handle); system("type DEMO.FL"); } Page -88- SCL1 Version 2.0 Reference Manual GetFreeMem Function: GetFreeMem Purpose: Gets the free memory reported by the DOS in your system. Declaration: long GetFreeMem(void); Returns: The return value is the amount of free memory, in bytes, reported by the DOS. Parameters: None Example: #include <scl1.h> main() { printf("Available memory: %li",GetFreeMem()); } Page -89- SCL1 Version 2.0 Reference Manual GetKey Function: GetKey Purpose: Waits and returns the pressed key's Scan/ASCII code. Declaration: unsigned int GetKey(void); Returns: The Scan/Ascii code of the pressed key. See Appendix "D" for the variables defined in SCL1KEYS.H. Parameters: None Example: #include <scl1.h> #include <scl1keys.h> main() { unsigned int Key; switch(Key=GetKey()) { case F1: . . case F2: . . } } Page -90- SCL1 Version 2.0 Reference Manual GetString Function: GetString Purpose: Saves and restores the cursor's size and position, displays a prompt and the current buffer contents, positions the cursor and fills the buffer with keyboard input. The type and number of characters are specified. Supports INSERT, DELETE, BACKSPACE, HOME and END editing keys and mouse input. If variable GS_Insert is set to "1" prior to calling GetString, it will start in the insert mode. When no entry has been made into the buffer the variable GS_Edit is set to "0", otherwise it is set to "1". If GS_Beep is set to "1" the console speaker will sound if an invalid key is pressed. The buffer must be initialized with a null terminated string or null string. Declaration: int GetString(int PColor, int PRow, int PCol, char* Prompt, int FColor, int FRow, int FCol, int MaxChar, unsigned int CharType, char *Buffer); Returns: Returns the number of characters in buffer or "-1" if the Esc key is pressed. Parameters: PColor - color attribute of the prompt (integer). PRow - row position where to display the prompt (integer). PCol - column position where to display the prompt (integer). Prompt - pointer to the prompt to be displayed (char). FColor - color attribute of the field (integer). FRow - row position where to display the field (integer). FCol - column position where to display the field (integer). MaxChar - length of the input field (integer). Page -91- SCL1 Version 2.0 Reference Manual GetString CharType - the mask of valid characters as described in function CheckChar. (refer to Appendix "D"). Buffer - pointer to the buffer to be used to store the field, it must be one digit larger than the field's size to place the string termination null character. Example: #include <scl1.h> #include <scl1clor.h> int Color1=BLACK_WHITE; int Color2=WHITE_BLACK; char Buffer[32]; main() { GetString(Color1,10,20,"Name:",Color2,10,28,31,CC_ANY,Buffer); } Page -92- SCL1 Version 2.0 Reference Manual GetTime Function: GetTime Purpose: Gets the system time. Declaration: char *GetTime(void); Returns: The return value is a pointer to a buffer that holds the system time in ASCII. Set global variables GT_Hours, GT_Minutes, GT_Seconds and GT_Hundredths to the system time. Parameters: None Example: #include <scl1.h> #include <scl1clor.h> int Color1=BLACK_WHITE; main() { WriteScreen(Color1,3,3,"Time:"); WriteScreen(Color1,3,9,GetTime()); } Page -93- SCL1 Version 2.0 Reference Manual GSSBox Function: GSSBox Purpose: Draws a box with one of 12 predefined types of frames. The minimum box size is 2 rows and 2 columns. The function does not perform bound checking, the box will spill out of the desired area if the coordinates are outside the screen range. The function draws a box frame and fills its interior. Three flags; Grow, Noise and Shadow can be specified. The grow flag signals the function to draw the box with a growing effect, the noise flag signals the function to make a swirling noise when drawing the box, and the shadow flag signals the function to add a shadow effect. If you do not specify a shadow color (using the SetShadowColor function) it will be XOR'ed to the current background color. Make sure to leave space for the shadow characters. You can define other types of frames using the SetUserBox function. Declaration: void GSSBox(int Color, int FrameType, int UpperRow, int LeftCol, int LowerRow, int RightCol,int GrowFl,int SoundFl, int ShadowFl); Returns: Nothing Parameters: Color - color attribute for the box (integer). FrameType - frame type, an integer value from 0 to 11 as follows, box frame 12 draws the user defined frame: ╔═════════╗ ┌─────────┐ ╓─────────╖ ╒═════════╕ ╒════════╕ ║ FRAME 0 ║ │ FRAME 1 │ ║ FRAME 2 ║ │ FRAME 3 │ │ FRAME 4│ ╚═════════╝ └─────────┘ ╙─────────╜ ╘═════════╛ └────────┘ ▄▄▄▄▄▄▄▄▄▄ ░░░░░░░░░░░ ▒▒▒▒▒▒▒▒▒▒ ▓▓▓▓▓▓▓▓▓▓ FRAME 5 ▌ FRAME 6▐ ░ FRAME 7 ░ ▒FRAME 8 ▒ ▓FRAME 9 ▓ ▀▀▀▀▀▀▀▀▀▀ ░░░░░░░░░░░ ▒▒▒▒▒▒▒▒▒▒ ▓▓▓▓▓▓▓▓▓▓ ██████████ ********** █FRAME 10█ *FRAME 11* ██████████ ********** Page -94- SCL1 Version 2.0 Reference Manual GSSBox (Note: You will not be able to print the correct frame types if your printer does not support the IBM extended ASCII character set.) UpperRow - upper row coordinate of the box (integer). LeftCol - left column coordinate of the box (integer). LowerRow - lower row coordinate of the box (integer). RightCol - right column coordinate of the box (integer). (Note: the home position is row 0, column 0.) GrowFl - flag to signal a growing box. If this value is "1" the box will grow from its center out. If the value is "0" the box will pop into the screen (integer). SoundFl - flag to signal a noise growing box. If the value is "1" when the box grows it will make a swirling noise. A value of "0" will draw a quiet box (integer). ShadowFl - flag to signal a shadow effect. If the value is "1" a shadow effect will be drawn, if the value is "0" no shadow effect will be drawn. The shadow will be XOR'ed to the background, if no shadow color have been defined (integer). Example: #include <scl1.h> #include <scl1clor.h> int Color1=WHITE_BLACK; main() { GSSBox(Color19,0,3,12,20,68,1,1,0); /* Will draw a growing, shadowed, double framed box between rows 3 & 20 and columns 12 & 68 */ } See also Box, Shadow, SetShadowColor, SetUserFrame. Page -95- SCL1 Version 2.0 Reference Manual HideMouse Function: HideMouse Purpose: Hides or removes the mouse cursor from the screen. Declaration: void HideMouse(void); Returns: Nothing Parameters: None Example: #include <scl1.h> main() { InitMouse(IM_SHOW); /* initialize mouse, turn cursor on */ if(MSE_MouseFl) { printf("We have a mouse, click the left button to turn mouse cursor off.\n"); WaitKeyMouse(); HideMouse(); printf("Click again to turn mouse cursor on.\n"); WaitKeyMouse(); ShowMouse(); printf("Click to exit.\n"); WaitKeyMouse(); } else printf("We don't have a mouse\n"); } } Page -96- SCL1 Version 2.0 Reference Manual InitMouse Function: InitMouse Purpose: Initializes the mouse for further use of the mouse functions. When you exit the program it takes care of resetting the mouse. Declaration: int InitMouse(int Cursor); Returns: Returns "-1" if an error has occurred that prevents the function to initialize the mouse correctly. Parameters: Cursor - this parameter tells InitMouse how to handle the mouse cursor. The following variables have been defined in SCL1.H; IM_SHOW - means to the show mouse cursor (integer). IM_NO_SHOW - means not to show the mouse cursor (integer). Example: #include <scl1.h> main() { InitMouse(IM_SHOW); /* initialize mouse, turn cursor on */ if(MSE_MouseFl) { printf("We have a mouse, click the left button to turn mouse cursor off.\n"); WaitKeyMouse(); HideMouse(); printf("Click again to turn mouse cursor on.\n"); WaitKeyMouse(); ShowMouse(); printf("Click to exit.\n"); WaitKeyMouse(); } else printf("We don't have a mouse\n"); } Page -97- SCL1 Version 2.0 Reference Manual InitUserError Function: InitUserError Purpose: Initialize user defined error codes for use with the ErrorBox function. You can redefine the standard error messages included in ErrorBox. Declaration: void InitUserError(struct ErrorMess *p); Returns: Nothing Parameters: The Error Message information is placed in an array of structures as follows: (The array of structures must be terminated with a "0"). struct ErrorMess{ int ErrorNum; char *Message; }; where, ErrorNum - user defined error number, an integer value above 256 (integer). If a predefined error message is initialized, the function will use the new values. This permits to change the error messages. Message - pointer to the user defined error message's text. Example: #include <scl1.h> struct ErrorMess em[]={ 256,"Please type either Y for YES\nor N for NO", 0}; main() { int Key; InitUserError(em); printf("\nInstall printer driver? (Y/N)\n"); Page -98- SCL1 Version 2.0 Reference Manual InitUserError do { Key=toupper(getch()); if(Key != 'Y' && Key != 'N') ErrorBox(256); else break; }while(1); } See also ErrorBox, ErrorShadowOff, ErrorShadowOn and SetErrorBoxColor. Page -99- SCL1 Version 2.0 Reference Manual InitVideo Function: InitVideo Purpose: Initialize video monitor to the alphanumeric display mode. Declaration: void InitVideo (void); Returns: Nothing Parameters: None Example: #include <scl1.h> main() { InitVideo(); printf("SCL1's InitVideo function has initialized your monitor\nto it's default alphanumeric mode.\n"); } Page -100- SCL1 Version 2.0 Reference Manual Int24ShadowOff Int24ShadowOn Function: Int24ShadowOff Int24ShadowOn Purpose: Enable or disable a shadow effect when using the TrapInt24 function. After any of these functions is called, all TrapInt24 messages will be displayed with (or without) a shadow effect. Declaration: void Int24ShadowOff(void); void Int24ShadowOn(void); Returns: Nothing. Parameters: None. Example: Int24ShadowOff(); /* Turn off shadow effect on error boxes */ Int24ShadowOn(); /* Turn on shadow effect on error boxes */ See TrapInt24 and SetTrapInt24Colors. Page -101- SCL1 Version 2.0 Reference Manual KeyReady Function: KeyReady Purpose: Scans the BIOS keyboard buffer for unprocessed keystrokes. Declaration: unsigned int KeyReady(void); Returns: Return the Scan/Ascii code of key in the BIOS buffer or "0" if it is empty. Parameters: None Example: #include <scl1.h> main() { while(!KeyReady()) printf("No key has been pressed!\n"); ClearKeyBuf(); } Page -102- SCL1 Version 2.0 Reference Manual KeyStatus Function: KeyStatus Purpose: Returns the shift, control and toggle key status. Declaration: unsigned char KeyStatus(void); Returns: The return value AND the following masks, defined in SCL1.H, are ">0" if the key is toggled or pressed. The mask values defined in SCL1.H are: INSERT, CAPSL, NUMSL, SCROLL, ALT, CTRL, LSHIFT and RSHIFT. Example: #include <scl1.h> #include <scl1keys.h> #include <scl1clor.h> int Color1=BLACK_WHITE; int Color2=WHITE_BLACK; main() { unsigned int Key; Key=KeyStatus(); if (Key&ALT) /* ALT key pressed */ WriteScreen(Color1,17,10,"Pressed "); else WriteScreen(Color2,17,10,"Not Pressed"); if (Key&INSERT) /* INSERT mode is on */ WriteScreen(Color1,17,34,"On "); else WriteScreen(Color2,17,34,"Off"); } Page -103- SCL1 Version 2.0 Reference Manual LineEditor Function: LineEditor Purpose: A full featured line editor. You can define all the parameters required for the line editor such as; where to display a prompt, size of the field, size of the display, colors, cursor size, default editing mode, etc. Declaration: int LineEditor(int Message,LEData *p,...); Returns: This is a dialog type function. See Appendix "E" for a description of the general operation of these functions. The return value is a message described in the Messages section. Parameters: The line editor information must be given in a structure defined as type LEData. The structure elements are as follows: typedef struct{ int PColor; int PRow; int PCol; char *Prompt; int FColor; int FRow; int FCol; unsigned int FLength; unsigned int FSize; int CType; int MaskFn; char *MaskArray; char *Buffer; char *FormatC; unsigned int *ExitKeys; int InsFlag; int InsertCur; int TypeOverCur; int CPaint; unsigned int StartPos; unsigned int EndPos; unsigned int EventInfo; unsigned int Position; unsigned int Scroll; int Edited; }LEData; Page -104- SCL1 Version 2.0 Reference Manual LineEditor where, PColor - color attribute for the prompt (integer). Row - row position where to display the for the prompt's display (integer). PCol - column position for the prompt's display (integer). Prompt - char pointer to the prompt. FColor - color attribute for the field (integer). FRow - row position for the field's display (integer). FCol - column position for the field's display (integer). FLength - field's display length. Number of characters to display. If the field size is larger than the display size, the length of the display line for the field (unsigned integer). FSize - maximum number of characters of the field. This number can be larger than the field length, in which case, the display will scroll horizontally when the cursor reaches the end of the available display length (unsigned integer). CType - type of characters to be accepted. Please refer to CheckChar for a description of the values defined in SCL1.H (integer). MaskFn - a flag to instruct the function to accept or discard the characters defined in the MaskArray array. A value of 0 will accept the characters and a value of 1 will discard them (integer). MaskArray - array of mask characters (null terminated). Buffer - buffer that holds the information to be edited. FormatC - a string that holds the characters to be used as format characters during editing. ExitKeys - null terminated array of unsigned integer Scan/Ascii values of the keys to exit. Page -105- SCL1 Version 2.0 Reference Manual LineEditor InsFlag - a flag to instruct the function of the default edit mode. ("1" = Insert,"0" = typeover)(integer). InsertCur - size of cursor when insert mode is toggled ("0" = no cursor, "1" = normal cursor, "2" = block sized cursor)(integer). TypeOverCur - size of cursor when typeover mode is toggled ("0"= no cursor, "1" = normal cursor, "2" = block sized cursor)(integer). CPaint - color to be used to mark a group of characters from the position defined by StartPos to EndPos. The CPaint value can be used to construct character blocks (integer). StartPos - start position of conditional paint characters (unsigned integer). EndPos - end position of conditional paint characters (unsigned integer). EventInfo - information about the keys that have been pressed (unsigned integer). Position - contains the current cursor position within the buffer (or offset)(unsigned integer). Scroll - horizontal scroll counter, keeps track of the cursor position when the field size is larger than the field length. Edited - a flag that keeps track of the field activity. A value of "0" means that the field has not been edited and a value of "1" means that the field has been edited (integer). Page -106- SCL1 Version 2.0 Reference Manual LineEditor Messages: Messages that can be sent to the LineEditor function: LE_INIT - Initialize the LEData structure to NULL and sets the following default values: PColor - set to white characters in a black background or the normal color defined by calling SetDialogColors. FColor - set to black characters in a white background or the reversed color defined by calling SetDialogColors. FLength - set to 40 columns. FSize - set to 40 columns. CType - set to CC_ANY, accept any character. Buffer - set to use a default internal buffer called DefBuf. ExitKeys - set to the default exit keys. InsFlag - set to the typeover mode. InsertCur - set to a value of "2". LE_DRAW - display the prompt and current edit buffer's information. LE_UPDATE_FIELD - display the current edit buffer's contents. Page -107- SCL1 Version 2.0 Reference Manual LineEditor LE_ACTIVE - edit the contents of the field buffer. The following edit keys have been defined: Key Action Left Arrow cursor one position to the left. Right Arrow cursor one position to the right. END cursor to end of field. HOME cursor to beginning of field. INSERT toggle insert mode on/off. BACKSPACE erase the character at current cursor position. Move remaining text to the left. LE_KEY - the parameter passed with this messages (Scan+Ascii code of the key) is a control key value that performs as if the control key has been pressed. LE_DATA - the parameter passed with this messages is an ASCII key value that performs as if that character has been typed. LE_POSITION_BEGIN - move cursor the start of the edit buffer. LE_POSITION_END - move cursor to the end of the edit buffer. LE_POSITION_UP - move cursor one position forward. LE_POSITION_DOWN - move cursor one position backwards. LE_SET_POSITION - set the cursor position. LE_CHARS_UP - moves all the text from the current cursor position one space forward. LE_CHARS_DOWN - moves all the text in the field from the current cursor position one space backwards. Page -108- SCL1 Version 2.0 Reference Manual LineEditor LE_CLEAR - clear the editor's buffer. LE_RESET - when this message is sent the field contents variables are reset to the default value. If the exit keys have not been defined they are set to the default exit keys. Messages that LineEditor can return: LE_OK - the requested action has been successfully performed. LE_EXIT_KEY - a key defined as an exit key has been pressed. LE_MOUSE_EVENT - the mouse has been clicked after pointing outside the Line Editor field. LE_BUFFER_END - you have reached the buffer's maximum size. LE_BUFFER_BEGIN - you have reached the beginning of the edit buffer. LE_ILLEGAL_KEY - a key that has not been defined as an exit key or that is not a legal key as defined for that field has been pressed. LE_BUFFER_FULL - the edit buffer is full. LE_ILLEGAL_POSITION- you have requested to move the cursor passed the maximum defined field length or left of the beginning position. LE_NEW_POSITION - a legal editing function is performed. LE_MY_MOUSE - response to a LE_CHECK_MOUSE message if the mouse has been clicked after pointing to the field area defined by the function. LE_DEL_NULL - you have pressed the delete key when the cursor has reached the buffer end. Example: #include <scl1.h> #include <scl1keys.h> #include <scl1clor.h> Page -109- SCL1 Version 2.0 Reference Manual LineEditor unsigned int ExitKeys[]={ENTER,ESC,0}; main() { LEData led; int Mess; char buffer[81]; Cls(WHITE_BLACK,CLS_ALL); /* clear screen */ memset(buffer,0,sizeof(buffer)); /* initialize buffer */ /* initialize Line Editor structure */ LineEditor(LE_INIT,&led); /* modify prompt and field position */ led.PRow=led.FRow=12; led.PCol=25; led.FCol=35; /* the field's screen length is of 20 characters but up to 80 characters can be entered, the data entry field will scroll automatically */ led.FLength=20; led.FSize=80; led.Prompt="Filename:"; /* prompt */ led.CType=CC_PATH | CC_CAPITALIZE; /* type of valid characters */ led.Buffer=buffer; /* use our buffer */ led.ExitKeys=ExitKeys; /* our defined exit keys */ PushCursor(); /* save cursor */ LineEditor(LE_DRAW,&led); /* draw */ /* Main loop: send ACTIVE message, LineEditor constantly returns information */ do { Mess=LineEditor(LE_ACTIVE,&led); if(Mess==LE_ILLEGAL_KEY) /* illegal key? */ TSound(440,10); /* beep */ /* loop until an exit key is pressed */ }while(Mess != LE_EXIT_KEY); PopCursor(); } Page -110- SCL1 Version 2.0 Reference Manual ListManager Function: ListManager Purpose: Displays a list of items and permits user selection of items. Mouse input is supported. Declaration: int ListManager(int NColor, int RColor,int Number, int Length,int Selection, int Lines, int Cols, struct ItemList*p); Returns: The return value is the number of the selected item. Parameters: The Item List message information must be given as an array of structures as follows: struct ItemList{ int Row,Col; char *String; }; where, Row - row position of where to display the item (integer). Col - column position where to display the item (integer). String - char pointer to the item text to be displayed. The parameters passed to the function are: NColor - color attribute for the normal display of items (integer). RColor - color attribute for the highlighted item (integer). Number - number of items defined (integer). Length - length of the items (integer). Selection - default selection (integer). Lines - number of lines to be displayed (integer). Page -111- SCL1 Version 2.0 Reference Manual ListManager Cols - number of columns to be displayed (integer). ItemList - pointer to the item list structure. Example: #include <scl1.h> #include <scl1clor.h> int Color1=BLACK_WHITE; int Color2=WHITE_BLACK; struct ItemList il[]={ 10,10,"Item #1", 10,20,"Item #2", 10,30,"Item #3", 12,10,"Item #4", 12,20,"Item #5", 12,30,"Item #6", }; main() { int ItemSelected; ItemSelected=ListManager(Color1,Color2,6,6,1,2,3,il); } See also ListWindow. Page -112- SCL1 Version 2.0 Reference Manual ListWindow Function: ListWindow Purpose: Displays an array of items in a window in columnar format. The user can use the arrow keys or the mouse to tag or select a desired item. When the list of items is large, the function displays scroll bars to let the user know that there are items not shown in the window. Declaration: int ListWindow(int Message,LWData *p,...); Returns: This is a dialog type function. See Appendix "E" for a description of the general operation of these functions. The return value is a message described in the Messages section. Parameters: The list window information must be given in a structure defined as type LWData. The structure elements are as follows: LWData structure: typedef struct{ int NColor; int RColor; int UpperRow; int LeftCol; int LowerRow; int RightCol; int FrameType; int ScrollBar; int BarColor; char **Array; char *TagArray; int TagColor; char *Title; int TitleColor; unsigned int *ExitKeys; int StaticWidth; unsigned int Items; unsigned int ColumnWidth; unsigned int FirstItem; unsigned int Position; unsigned int *ExitKeys; int WindowLines; int WindowCols; Page -113- SCL1 Version 2.0 Reference Manual ListWindow int TotalCols; int TotalWindowItems; int OldHBlock; unsigned int EventInfo; }LWData; where, NColor - color attribute for normal display (integer). RColor - color attributes for reversed display (integer). UpperRow - upper row coordinate of the window (integer). LeftCol - left column coordinate of the window (integer). LowerRow - lower row coordinate of the window (integer). RightCol - right column coordinate of the window (integer). FrameType - any of the frame types that can be used with the Box or GSSbox functions (integer). ScrollBar - a flag to signal the function to draw scroll bars at the bottom of the display to indicate the relative position of the cursor (integer). BarColor - color attributes for the scroll bars (integer). Array - pointer to a null terminated array of pointers to be displayed. TagArray - an array that holds which item has been tagged. If a null pointer is specified the function will not permit tagging. An array element value of "0" and "1" indicate the status for untagged and tagged (char). Page -114- SCL1 Version 2.0 Reference Manual ListWindow TagColor - color attributes to be used for displaying a tagged item (integer). Title - char pointer to text to be displayed in the window's top row as a title. TitleColor - color attributes for the title's display (integer). ExitKeys - an array of keys defined to exit the function (unsigned integer). StaticWidth - a value of "0" means that the number of columns will be determined by the maximum length of any of the items, a value of "1" sets the width of the columns to the value defined with ColumnWidth (integer). Items - structure element (used internally) that holds the quantity of items in the array (unsigned integer). ColumnWidth - width of each column to be displayed window (unsigned integer). FirstItem - structure element (used internally) that holds the position of the first array element (unsigned integer). Position - structure element (used internally) that holds the active position of the display (unsigned integer). Note this element should not be modified by the calling program but can be read. WindowLines - structure element (used internally) that holds the number of lines in the List Window (integer). WindowCols - structure element (used internally) that holds the number of columns in the List Window (integer). TotalCols - structure element (used internally) that holds the maximum number of columns in the window (integer). Page -115- SCL1 Version 2.0 Reference Manual ListWindow TotalWindowItems - structure element (used internally) that holds the number of items (integer). OldHBlock - structure element (used internally) that holds the position of the relative position indicating scroll bar block (integer). EventInfo - information about the keys that have been pressed (unsigned integer). Messages: The following messages can be sent to ListWindow: LW_INIT - initialize the LWData structure to NULL and set the following default values: NColor - set to white characters in a black background or the normal color defined by calling SetDialogColors. RColor - set to black characters in a white background or the reversed color defined by calling SetDialogColors. LowerRow - one row less than the screen length. RightCol - one column less than the screen width. FrameType - set to frame type "1" (single line). ScrollBar - set to draw scroll bars. BarColor - set to black characters in a white background or the reversed color defined by calling SetDialogColors. TagColor - set to black characters in a white background or the reversed color defined by calling SetDialogColors. TitleColor - set to white characters in a black background or the normal color defined by calling SetDialogColors. OldHBlock - set to "-1". Page -116- SCL1 Version 2.0 Reference Manual ListWindow LW_DRAW - display the list window. LW_WRITE - draws the window and the list of items to the screen. LW_ACTIVE - browse through the displayed items and permit the selection or tagging of them using the cursor movement keys as follows: Key action Up Arrow cursor one item up. Down Arrow cursor one item down. Left Arrow cursor one item to the left. Right Arrow cursor one item to the right. END cursor to end of list. HOME cursor to beginning of list. Page Up cursor one screen up. Page Down cursor one screen down. LW_DRAW_BORDER - draw the List Window's border. LW_POSITION_BEGIN - move cursor to the first item. LW_POSITION_END - move cursor to the last item. LW_POSITION_UP - move cursor to the previous item. LW_POSITION_DOWN - move cursor to the next item. LW_SET_POSITION - move cursor to a specific item. The item number is passed as a parameter. LW_CLS - clear the list window data area. LW_CHECK_MOUSE - check if the mouse has been clicked after pointing to the area defined by the function. LW_RESET - when this message is sent the position variables are reset to the default value. If the exit keys have not been defined they are set to the default exit keys. Page -117- SCL1 Version 2.0 Reference Manual ListWindow The following messages can be returned by ListWindow: LW_NULL_ARRAY - no item array has been defined. LW_OK - the requested action has been performed. LW_EXIT_KEY - a key that has been defined as an exit key has been pressed. LW_MOUSE_EVENT - the mouse has been clicked but it has not been pointed to the area defined by the function. LW_BUFFER_END - you have requested to move the cursor passed the last item. LW_BUFFER_BEGIN - you have requested to move the cursor up passed the first active item. LW_ILLEGAL_KEY - a key that has not been defined has been pressed. LW_ILLEGAL_POSITION - you have requested to move the cursor to an invalid position. LW_NEW_POSITION - the cursor position has been updated. LW_MOUSE_SELECT - one of the elements have been selected by double clicking the mouse. LW_MY_MOUSE - response to a LW_CHECK_MOUSE message if the mouse has been clicked after pointing to the field area defined by the function. LW_NEW_MOUSEPOS - you have moved the cursor by clicking the mouse after pointing to an item. LW_BLOCK_MARK - you have tagged a group of items using your mouse. Page -118- SCL1 Version 2.0 Reference Manual ListWindow Example: #include <scl1.h> #include <scl1clor.h> char *Items[]={ /* Array of items to display */ "11111", "22222", "33333", "44444", "55555", "66666", "77777", "88888", "99999", "00000", 0, /* terminated with a "0" */ }; char TagA[10]; int Color1=BLACK_WHITE; int Color2=WHITE_BLACK; main() { int EMess; LWData lw; /* set lw as type LWData */ ListWindow(LW_INIT,&lw); lw.UpperRow=5; /* Set window size */ lw.LowerRow=10; lw.LeftCol=30; lw.RightCol=40; lw.RColor=Color2; lw.TagArray=TagA; lw.Array=Items; ListWindow(LW_DRAW,&lw); do { EMess=ListWindow(LW_ACTIVE,&lw); }while(EMess != LW_EXIT_KEY); } Page -119- SCL1 Version 2.0 Reference Manual MakeDir Function: MakeDir Purpose: Creates a new directory. Declaration: int MakeDir(char *Path); Returns: The return value is "0" if no error occurs or the DOS error code if an error occurs. (See Appendix "A", FILE FUNCTIONS, for more information). Parameters: Path - char pointer to a string holding the new directory name. Example: #include <scl1.h> main() { MakeDir("SCL1"); } Page -120- SCL1 Version 2.0 Reference Manual Menu Function: Menu Purpose: Displays a scrolling or moving bar type menu. A selection is made by either pressing the highlighted menu option letter or by scrolling the highlighted bar using the arrow keys and then pressing the ENTER (RETURN) key. This function permits full control of the menu's appearance, size and position. The menu items can be placed anywhere in the screen and in any desired order, you are not limited to placing all the menu options in successive lines. Declaration: int Menu(int NColor, int RColor, int HColor, int NumOpt, struct MenuOpt *mo); Returns: The highlighted selection number (>0) or -1 if ESC is pressed. Parameters: The menu information must be entered as an array of structures as follows; with one array element for each menu option: struct MenuOpt{ int Row,Col; char *String; char Letter; }; where: Row - row position for the menu item (integer). Col - column position for the menu item (integer). String - pointer to the menu item text. Letter - letter to be highlighted for fast keyboard selection of the menu item (char). Page -121- SCL1 Version 2.0 Reference Manual Menu The parameters passed to the function are: NColor - color attribute for the menu background and foreground (integer). RColor - color attribute for the highlighted item menu bar (integer). HColor - color attribute for the highlighted quick selection menu item letter (integer). NumOpt - number of menu options (integer). MenuOpt - pointer to the menu structure previously defined. Example: #include <scl1.h> #include <scl1clor.h> struct MenuOpt Mainmenu[7]={ /*Array of structures with seven elements */ 5,24,"Screen Related Functions ",'S', /* First option */ 7,24,"Keyboard Handling Functions ",'K', /* Second option */ 9,24,"Mouse Handling Functions ",'M', /* Third option */ 11,24,"Program Flow Functions ",'P', /* Fourth option */ 13,24,"File Handling Functions ",'F', /* Fifth option */ 15,24,"Background and Miscellaneous",'B', /* Sixth option */ 17,24,"Exit Demo ",'E', /* Seventh option */ }; int Color1=BLACK_WHITE; int Color2=WHITE_BLACK; int Color3=BLACK_WHITE+HIGHLIGHT; main() { int Selection; Box(Color1,5,1,5,18,25); /* Box for menu */ WriteScreen(Color1,2,11,"FUNCTIONS"); /* Menu title */ Selection=Menu(Color1,Color2,Color3,7,Mainmenu); } Page -122- SCL1 Version 2.0 Reference Manual MenuSys Function: MenuSys (OBSOLETE, use the MenuSystem function, this function will eventually be removed from future versions of SCL1.) Purpose: Displays a pull-down menu system in the top of the screen. The number of pull-down menus is defined by the programmer. All the pull-down menus perform and are defined as for the Menu function. The function requires the programmer to define various structures and data blocks, although this approach seems to be complex it gives full control of the size, position and appearance of the menu. Supports mouse control. Declaration: int MenuSys(int NColor,int RColor,int HColor, int MenuNumber,struct BarMenu *bm, struct MenuSysData *msd); Returns: Return value is the highlighted selection number, "-1" if the ESC key is pressed or "0" if no selection is made. The function returns two digits, the first corresponding to the pull-down menu number and the second corresponding to the option selected in that menu. The calling program must create a loop for calling the function when required. Parameters: The menu information must be given as an array of structures as follows: 1. Define the Top Row menu information as follows, one element for each of the main options: struct BarMenu{ int StartCol,EndCol; char String[20]; }; where; StartCol - column position of the first character of the option's prompt (integer). EndCol - column position of the last character of the option's prompt (integer). Page -123- SCL1 Version 2.0 Reference Manual MenuSys String - pointer to a string value containing the option's prompt, equal to or shorter than 19 characters (char). Note: The StartCol and EndCol information is used by MenuSys to determine the mouse range for that option and to highlight it when selected, for proper operation make sure that options do not overlap. 2. Define one MenuOpt structure for each of the pull-down menus. This structure is identical to that used by the Menu and MouseMenu functions: struct MenuOpt{ int Row,Col; char *String; char Letter; }; where: MenuOpt - name or reference to the menu. Row - row position for the menu item (integer). Col - column position for the menu item (integer). String - pointer to the menu item text (char). Letter - letter to be highlighted for fast keyboard selection of the menu item (char). 3. Define a PopMenuData structure for each of the pull-down menus as follows: struct PopMenuData{ int L1,C1,L2,C2; int NumberOption; char *WinBuffer; struct MenuOpt *Menust; }; where; L1 - upper left row coordinate of the box used to enclose the pull-down menu (integer). Page -124- SCL1 Version 2.0 Reference Manual MenuSys C1 - upper left column coordinate of the box (integer). L2 - lower right row coordinate of the box (integer). C2 - lower right column coordinate of the box (integer). NumberOptions - number of options of the pull-down menu (integer). WinBuffer - buffer to store the screen area used when popping out the pull-down menu (char). MenuOpt - pointer to the MenuOption structure corresponding to that pull-down menu. 4. Define a MenuSysData structure with one element for each of the pull-down menus as follows: struct MenuSysData{ unsigned int Key; struct PopMenuData *PMenu; }; where; Key - key to activate that pull-down menu. (required for keyboard control of the menu system) (unsigned integer). PopMenuData - pointer to the PopMenuData structure. The MenuSys function is called with the following parameters: NColor - color attribute of the menus (integer). RColor - reverse color attributes (integer). HColor - highlight color attributes (integer). MenuNumber - number of pull-down menus (integer). BarMenu - pointer to the BarMenu structure. MenuSysData - pointer to the MenuSysData structure. Page -125- SCL1 Version 2.0 Reference Manual MenuSys Example: #include <scl1.h> #include <scl1clor.h> #include <scl1keys.h> int Color1=BLACK_WHITE; int Color2=WHITE_BLACK; int Color3=BLACK_WHITE+HIGHLIGHT; /* Bar Menu Structure */ struct BarMenu bd[]={ 3,9,"F1 File", 17,23,"F2 Edit", }; /* First pop-menu structure */ struct MenuOpt Men1[]={ 2,5,"New ",'N', 3,5,"Open ",'O', 4,5,"Close ",'C', 5,5,"Save ",'S', 6,5,"Exit ",'E', }; /* Second pop-menu structure */ struct MenuOpt Men2[]={ 2,19,"Copy ",'C', 3,19,"Delete ",'D', 4,19,"Insert ",'I', 5,19,"Cancel ",'a'}; struct PopMenuData bd1[]={ 1,3,7,13, 5, WinBuf1, Men1, 1,17,6,27, 4, WinBuf1, Men2, }; Page -126- SCL1 Version 2.0 Reference Manual MenuSys struct MenuSysData msd1[]={ F1, &bd1[0], F2, &bd1[1], }; main() { int Selection; /* Draws the top row prompts*/ DrawBarMenu(Color1,Color2,2,0,bd); /* Loop until the exit option is selected */ do { Selection=MenuSys(Color1,Color2,Color3,2,bd,msd1); /* Discard any invalid key pressed */ if(!((KeyReady()>F1)&&(KeyReady()<F4))) ClearKeyBuf(); }while((Selection==0)||(Selection!=15)); } In the above example the exit option is the fifth of the first pull-down menu. Page -127- SCL1 Version 2.0 Reference Manual MenuSystem Function: MenuSystem Purpose: Displays a pull-down menu system in the top of the screen. The function requires the programmer to define various structures and data blocks, although this approach seems to be complex it gives full control of the size, position and appearance of the menu. Supports mouse control. This is a dialog type function. Declaration: int MenuSystem(int Message,MSData *msd,...); Returns: This is a dialog type function. See Appendix "E" for a description of the general operation of these functions. The return value is a message described in the Messages section. Parameters: The menu information must be given in an array of structures as follows; one element for each pull-down menu: 1. The top row menu information is defined as an array of structures type MSBar as follows, one element for each of the main options: typedef struct{ int StartCol; int EndCol; unsigned int Key; char *String; }MSBar; where; StartCol - column position of the first character of the option's prompt (integer). EndCol - column position of the last character of the option's prompt (integer). Key - unsigned integer structure member that indicates which key will be used to call the pull-down menu. (This is important when using keyboard input). Page -128- SCL1 Version 2.0 Reference Manual MenuSystem String - pointer to a string value containing the option's prompt. Note: The StartCol and EndCol information is used by MenuSystem to determine the mouse range for that option and to highlight it when selected. For proper operation make sure that options do not overlap. 2. Each pull-down menu is defined as an array of structures type MSOptions. The structure is similar to that used for the Menu function. typedef struct{ int Row; int Col; char *String; char Letter; }MSOptions; where: Row - row position for the menu item (integer). Col - column position for the menu item (integer). String - pointer to the menu item text. Letter - letter to be highlighted for fast keyboard selection of the menu item (char). 3. The pull down menu box information is defined in a structure type MSWindows as an array of structures for the menusystem, one element for each pull-down menu as follows: typedef struct{ int UpperRow; int LeftCol; int LowerRow; int RightCol; int Number; char *WinBuffer; MSOptions *mso; }MSWindow; Page -129- SCL1 Version 2.0 Reference Manual MenuSystem where; UpperRow - upper row coordinate of the box used to enclose the pulldown menu (integer). LeftCol - left column coordinate of the box (integer). LowerRow - lower row coordinate of the box (integer). RightCol - right column coordinate of the box (integer). Number - number of options of the pull-down menu (integer). WinBuffer - buffer to store the screen area used when popping out the pull-down menu. MSOptions - pointer to the MSOptions structure corresponding to that pull-down menu. 4. The remaining information is defined in a structure type MSData as follows: typedef struct{ int BarNColor; int BarRColor; int MenuNColor; int MenuRColor; int MenuHColor; MSBar *msb; MSWindow *msw; int Number; int Menu; int Option; unsigned int EventInfo; }MSData; where; BarNColor - normal color attributes for top row or bar menu (integer). BarRColor - reversed color attributes for top row or bar menu (integer). Page -130- SCL1 Version 2.0 Reference Manual MenuSystem MenuNColor - normal color attributes for the pull-down menus (integer). MenuRColor - Reversed color attributes for the pull-down menus (integer). MenuHColor - highlight color attributes for hot-keys in pull down menus (integer). MBar - pointer to the corresponding MSBar structure. MSWindow - pointer to the corresponding MSWindow structure. Number - number of pull-down menus in the system (integer). Menu - structure member holding the active pull-down menu number (integer). Option - structure member holding the active option of the selected pull-down menu (integer). EventInfo - structure member holding the event information for the menusystem. (unsigned integer). MenuSysData - pointer to the MenuSysData structure. Messages: The following messages can be sent to Menusystem: MS_INIT - initialize the MSData structure to NULL and set the following values as follows: BarNColor - set to black characters in a white background or the reversed color defined by calling SetDialogColors. BarRColor - set to white characters in a black background or the normal color defined by calling SetDialogColors. MenuNColor - set to white characters in a black background or the normal color defined by calling SetDialogColors. Page -131- SCL1 Version 2.0 Reference Manual MenuSystem MenuRColor - set to black characters in a white background or the reversed color defined by calling SetDialogColors. MenuHColor - set to highlighted white characters in a black background or the normal color defined by calling SetDialogColors. MS_DRAW - draw the bar menu. MS_CHECK - checks if any key or mouse event related to the MenuSystem has been activated in which case it will retain control and respond to the following keys: Key action Up Arrow cursor to previous option. Down Arrow cursor to next option. Left Arrow select previous pull-down menu. Right Arrow select next pull-down menu. MS_KEY - the parameter passed with this message (Scan+Ascii code of the key) is a control key value that performs as if the control key has been pressed. MS_SHADOW_ON - turn on a shadow effect for pull-down menus. Make sure to set enough space for the shadow characters in the MSWindows structure. MS_SHADOW_OFF - turn off shadow effect on pull-down menus. MS_LINE_ON - draw horizontal lines on empty spaces inside a menu box. MS_LINE_OFF - do not draw horizontal lines on empty spaces in menu box (default). MS_SET_FRAME_TYPE - sets the frame type for pull down menus to the type specified with an additional parameter (default is single line). Page -132- SCL1 Version 2.0 Reference Manual MenuSystem MS_SET_BAR_ROW - sets the row position where to display the bar menu to the value specified with an additional parameter (default is "0"). MS_SET_BAR_START - sets the column position where the bar menu starts to the value specified with an additional parameter (default is "0"). MS_SET_BAR_END - sets the column position where the bar menu ends to the value specified with an additional parameter (default is the maximum screen width). MS_ALT_ON - set ALT key to bring down pull-down menus. MS_ALT_OFF - disable the ALT key to bring pull-down menus. MS_SET_FRAME_COLOR - set the pull-down menu box' frame color, if this message is not sent it is set to normal color. MS_RESET_FRAME_COLOR - reset the pull-down menu box's frame to normal color. The following messages can be returned by Menusystem: MS_NO_SELECT - no selection has been made. MS_OK - action requested has been successfully performed. MS_SELECT - a selection has been made. This means that the structure element containing the selection information must be checked to determine what has been the selection. MS_CANCEL - the mouse has been clicked after pointing outside the window area or the "ESC" key has been pressed. Page -133- SCL1 Version 2.0 Reference Manual MenuSystem Example: #include <scl1.h> #include <scl1keys.h> #include <scl1clor.h> MSBar msb[]={ /* Menu-bar data: Start and end column of each option Menu's key SCAN-ASCII code String */ 1,6,0x2100," File ", 7,12,0x1200," Edit ", }; /* first pull-down menu row, column position string hot-key */ MSOptions mso0[]={ 2,1," Load ",'L', 3,1," Save ",'S', 4,1," Quit ",'Q', }; /* second pull-down menu */ MSOptions mso1[]={ 2,7," Mark ",'M', 3,7," Cut ",'C', 4,7," Copy ",'y', 5,7," Paste ",'P', }; /* buffer for storing pull down menu screen area */ char WindowBuf[140]; Page -134- SCL1 Version 2.0 Reference Manual MenuSystem /* Pull-down menu box & window information top left corner and bottom right corner coordinates number of options buffer for saving screen area MSOptions structure */ MSWindow msw[]={ 1,0,5,7,3,WindowBuf,mso0, 1,6,6,14,4,WindowBuf,mso1, }; /* This structure links all previous structures */ MSData msd= { /* bar-menu colors */ BLACK_WHITE,WHITE_BLACK+HIGHLIGHT, /* pull-down menu colors */ WHITE_BLACK,BLACK_WHITE,WHITE_BLACK+HIGHLIGHT, /* MSBar, MSWindow structures, number of menus and internal variables */ msb,msw,2,0,0,0}; main() { int Mess; InitMouse(IM_SHOW); /* initialize mouse */ /* Draw shadows */ MenuSystem(MS_SHADOW_ON,(MSData *)0); /* MenuSystem will be ALT sensitive */ MenuSystem(MS_ALT_ON,(MSData *)0); /* draw */ MenuSystem(MS_DRAW,&msd); Page -135- SCL1 Version 2.0 Reference Manual MenuSystem do { /* a key pressed? */ if(Mess=KeyReady()) { /* send key to MenuSystem */ Mess=MenuSystem(MS_KEY,&msd,Mess); /* If we still have a key it means it was not a MenuSystem key, discard key. If your program needs to service the keyboard you should do it here. */ if(KeyReady()) GetKey(); } else /* Let MenuSystem check if the mouse has been clicked or a selection has been made */ Mess=MenuSystem(MS_CHECK,&msd); if(Mess==MS_SELECT) { /* a selection was made, msd.Menu=selected menu */ switch(msd.Menu) { case 1: /* first menu, msd.Option=selected option */ switch(msd.Option) { case 1: /* first option */ MessageOn(BLACK_WHITE,"Load"); WaitTime(100); MessageOff();break; case 2: /* second option */ MessageOn(BLACK_WHITE,"Save"); WaitTime(100); MessageOff();break; Page -136- SCL1 Version 2.0 Reference Manual MenuSystem case 3: /* third option */ MessageOn(BLACK_WHITE,"Quit"); WaitTime(100); MessageOff(); break; } break; case 2: /* second menu */ switch(msd.Option) { case 1: /* first option */ MessageOn(BLACK_WHITE,"Mark"); WaitTime(100); MessageOff(); break; case 2: /* second option */ MessageOn(BLACK_WHITE,"Cut"); WaitTime(100); MessageOff(); break; case 3: /* third option */ MessageOn(BLACK_WHITE,"Copy"); WaitTime(100); MessageOff(); break; case 4: /* fourth option */ MessageOn(BLACK_WHITE,"Paste"); WaitTime(100); MessageOff(); break; } break; } } }while(msd.Menu != 1 || msd.Option != 3); } Page -137- SCL1 Version 2.0 Reference Manual MessageOff Function: MessageOff Purpose: Removes the message box displayed by MessageOn and restores the screen's previous contents. Declaration: void MessageOff(void); Returns: Nothing Parameters: None Example: #include <scl1.h> #include <scl1clor.h> main() { int i; char buffer[8]; memset(buffer,0,sizeof(buffer)); /* display message */ MessageOn(WHITE_BLACK,"Counting to 30,000..."); /* loop */ for(i=0;i < 30000; i++) /* write inside MessageOn screen area */ WriteScreen(WHITE_BLACK,11,38,Bin2Ascii((long)i,buffer)); /* restore screen */ MessageOff(); } See also MessageOn, MessageShadowOff and MessageShadowOn. Page -138- SCL1 Version 2.0 Reference Manual MessageOn Function: MessageOn Purpose: Displays a message inside a box in the center of the screen. The screen area is saved and is restored when MessageOff is called. Declaration: void MessageOn(int Color, char *String); Returns: Nothing Parameters: Color - Box/message color (integer). String - pointer to string. Note: Messages are written inside a box. They can have up to 5 lines with up to 40 characters each. Use control character '\n' to indicate new line. The box will stay on the screen until MessageOff is called. Each line will be centered in the window. Lines will also be centered vertically. Example: #include <scl1.h> #include <scl1clor.h> main() { int i; char buffer[8]; memset(buffer,0,sizeof(buffer)); /* display message */ MessageOn(WHITE_BLACK,"Counting to 30,000..."); /* loop */ for(i=0;i < 30000; i++) /* write inside MessageOn screen area */ WriteScreen(WHITE_BLACK,11,38,Bin2Ascii((long)i,buffer)); /* restore screen */ MessageOff(); } See also MessageOff, MessageShadowOff and MessageShadowOn. Page -139- SCL1 Version 2.0 Reference Manual MessageShadowOff MessageShadowOn Function: MessageShadowOff MessageShadowOn Purpose: Displays or disable a shadow effect when using the MessageOn/MessageOff functions. After any of these functions are called all subsequent calls to the MessageOn function will be displayed with (or without) a shadow effect. Declaration: void MessageShadowOff(void); void MessageShadowOn(void); Returns: Nothing. Parameters: None. Example: #include <scl1.h> #include <scl1clor.h> main() { int i; MessageOn(WHITE_BLACK,"MessageOn function without shadow\nPress any key..."); GetKey(); MessageOff(); MessageShadowOn(); MessageOn(WHITE_BLACK,"MessageOn function WITH shadow \nPress any key..."); GetKey(); MessageOff(); MessageShadowOff(); MessageOn(WHITE_BLACK,"MessageOn function again\nwithout shadow\nPress any key..."); GetKey(); MessageOff(); } See MessageOn and MessageOff. Page -140- SCL1 Version 2.0 Reference Manual MouseButton Function: MouseButton Purpose: A Mouse Button is a prompt that can be placed anywhere within the screen area and, when that when pointed and clicked by the mouse performs a given action. It performs as a sensitive screen prompt. The selected button is drawn in the specified color with or without a enclosing box. Most functions, like FileBox, use Mouse Buttons (in this case to select load or cancel). If you require more than one Mouse Button use the Fields2 function. Declaration: int MouseButton(int Message,MBData *p); Returns: This is a dialog type function. See Appendix "E" for a description of the general operation of these functions. The return value is a message described in the Messages section. Parameters: The MouseButton information must be given in a structure, type MBData, as follows: Structure type MBData: typedef struct{ int NColor; int RColor; int UpperRow; int LeftCol; int LowerRow; int RightCol; int PRow; int PCol; char *Prompt; int BoxFlag; int ActiveFlag; unsigned int *ExitKeys; unsigned int EventInfo; }MBData; where, NColor - color attribute used when button is not selected (integer). Page -141- SCL1 Version 2.0 Reference Manual MouseButton RColor - Color used for a selected button (integer). UpperRow - upper row coordinate of the Mouse Button area (integer). LeftCol - left column coordinate of the Mouse Button area (integer). LowerRow - lower row coordinate of the Mouse Button area (integer). RightCol - right column coordinate of the Mouse Button area (integer). PRow - row coordinate of the Mouse Button text (integer). PCol - column coordinate of the Mouse Button text (integer). Prompt - char pointer to the Mouse Button text. BoxFlag - a flag to indicate if a box shall be drawn around a Mouse Button (integer). ActiveFlag - a flag to indicate if the Mouse Button is active (integer). ExitKeys - an array of keys defined to exit the function (unsigned integer). EventInfo - variable that holds the key pressed when you exit the function or a non defined key is pressed (unsigned integer). Messages: The following messages can be sent to MouseButton: MB_INIT - initialize the MBData structure to NULL and set the following default values: NColor - set to white characters in a black background or the normal color defined by calling SetDialogColors. Page -142- SCL1 Version 2.0 Reference Manual MouseButton RColor - set to black characters in a white background or the reversed color defined by calling SetDialogColors. MB_DRAW - display the Mouse Button. MB_ACTIVE - move the cursor to the Mouse Button. This message is used by the Fields2 function. MB_CHECK_MOUSE - check to see if the mouse has been clicked after pointing to the Mouse Button. MB_RESET - when this message is sent Mouse Button variables are reset to the default value. If the exit keys have not been defined they are set to the default exit keys. The following messages can be returned by MouseButton: MB_OK - the function has performed the requested action. MB_EXIT_KEY - a key that has been defined as an exit key has been pressed. MB_MOUSE_EVENT - the mouse has been clicked after pointing outside the area defined by the function. MB_ILLEGAL_KEY - a key that has not been defined has been pressed. MB_MOUSE_SELECT - you have clicked your mouse after pointing to the Mouse Button. MB_MY_MOUSE - response to a MB_CHECK_MOUSE message if the mouse has been clicked after pointing to the area defined by the function. Page -143- SCL1 Version 2.0 Reference Manual MouseButton Example: #include <scl1.h> #include <scl1keys.h> main() { int EMess; MBData mb1; Cls(WHITE_BLACK,CLS_ALL); MouseButton(MB_INIT,&mb1); mb1.LeftCol=12; mb1.RightCol=19; mb1.NColor=Color1; mb1.RColor=Color2; mb1.UpperRow=6; mb1.Prompt="< LOAD >";; MouseButton(MB_DRAW,&mb1); do { EMess=MouseButton(MB_ACTIVE,&mb1); }while(EMess != MB_EXIT_KEY && EMess != MB_MOUSE_SELECT); } Page -144- SCL1 Version 2.0 Reference Manual MouseMenu Function: MouseMenu Purpose: Displays a scrolling or moving bar type menu. A selection is made by either pressing the highlighted menu option letter, by scrolling the highlighted bar using the arrow keys and then pressing the ENTER (RETURN) key or by moving the mouse cursor to the desired line and clicking the left mouse button. This function permits full control of the menu's appearance, size and position. The menu items can be placed anywhere in the screen and in any desired order, you are not limited to placing all the menu options in successive lines. Declaration: int MouseMenu(int NColor, int RColor, int HColor, int NumOpt, struct MenuOpt *k, int XMin, int XMax, int YMin, int YMax); Returns: The highlighted selection number (>1) or -1 if ESC is pressed or if mouse is clicked outside the menu area. Parameters: The menu information must be entered as an array of structures as follows; with one array element for each menu option: struct MenuOpt{ int Row,Col; char *String; char Letter; }; where: Row - row position for the menu item (integer). Col - column position for the menu item (integer). String - pointer to the menu item text. Letter - letter to be highlighted for fast keyboard selection of the menu item (char). Page -145- SCL1 Version 2.0 Reference Manual MouseMenu The parameters passed to the function are: NColor - color attribute for the menu background and foreground (integer). RColor - color attribute for the highlighted item menu bar (integer). HColor - color attribute for the highlighted quick selection menu item letter (integer). NumOpt - number of menu options (integer). MenuOpt - pointer to the menu structure previously defined. XMin - minimum row position of menu area (integer). XMax - maximum row position of menu area (integer). YMin - minimum column position of menu area (integer). YMax - maximum column position of menu area (integer). Example: #include <scl1.h> #include <scl1clor.h> struct MenuOpt Mainmen[7]={/*Array of structures with seven elements */ 5,24,"Screen Related Functions ",'S', /* First option */ 7,24,"Keyboard Handling Functions ",'K', /* Second option */ 9,24,"Mouse Handling Functions ",'M', /* Third option */ 11,24,"Program Flow Functions ",'P', /* Fourth option */ 13,24,"File Handling Functions ",'F', /* Fifth option */ 15,24,"Background and Miscellaneous",'B', /* Sixth option */ 17,24,"Exit Demo ",'E', /* Seventh option */ }; Page -146- SCL1 Version 2.0 Reference Manual MouseMenu main() { int Selection; Cls(WHITE_BLACK,CLS_ALL); InitMouse(IM_SHOW); Box(WHITE_BLACK,5,1,5,18,25); /* Box for menu */ WriteScreen(WHITE_BLACK,2,11,"FUNCTIONS"); /* Menu title */ Selection=MouseMenu(WHITE_BLACK,BLACK_WHITE, WHITE_BLACK+HIGHLIGHT,7,Mainmen,1,5,18,25); Cls(WHITE_BLACK,CLS_ALL); if(Selection > 0) printf("You have selected option %i\n",Selection); else printf("You have pressed ESCAPE or clicked the mouse outside the menu area.\n"); } Page -147- SCL1 Version 2.0 Reference Manual MoveFilePt Function: MoveFilePt Purpose: Moves the file pointer to the current location plus an offset. Declaration: int MoveFilePt(int Handle, unsigned long Bytes); Returns: The return value is "0" if no error occurs or the DOS error code if an error occurs. (See Appendix "A", FILE FUNCTIONS, for more information). Parameters: Handle - number is given by DOS when you open a file (integer). Bytes - number of bytes for offset (unsigned long integer). Example: #include <scl1.h> #include <string.h> /* This example creates a file with several names in lower-case. We will then open the file for appending data using MoveFilePt by moving the file pointer to the end of the file. */ struct NAME_REC{ /* Our file format */ char Name[7]; }nr; /* nr will be used as a buffer for converting strings to uppercase */ /* This is the data of the file we will create */ struct NAME_REC names[]={ "John", "Mary", "Robert", "Ann"}; struct NAME_REC newname={"Susan"}; main() { int handle; long filesize; Page -148- SCL1 Version 2.0 Reference Manual MoveFilePt /* create file */ if(Buf2Disk("DEMO.FL",(char *)names,sizeof(names))) { printf("Error creating file\n"); exit(-1); } /* Open file for reading and writing */ OpenFile("DEMO.FL",&handle,DOS2_RW); /* Get file size */ filesize=GetFileSize(handle); /* move file pointer to end of file */ MoveFilePt(handle,filesize); /* write our data */ WriteFile(handle,(char *)&newname,sizeof(struct NAME_REC)); } CloseFile(handle); } See also MoveFilePtOffset. Page -149- SCL1 Version 2.0 Reference Manual MoveFilePt2Offset Function: MoveFilePt2Offset Purpose: Moves the file read write pointer to an offset from the beginning of the file. Declaration: int MoveFilePt2Offset(int Handle, unsigned long Bytes); Returns: The return value is 0 if no error occur or the DOS error code if an error occur. (See Appendix "A", FILE FUNCTIONS, for more information). Parameters: Handle - number is given by DOS when you open a file (integer). Bytes - number of bytes for offset (unsigned long integer). Example: #include <scl1.h> #include <string.h> /* This example creates a file with several names in lower- case. We will read this file one record at a time into our buffer and convert the string to uppercase before rewriting it back to disk. For simplicity, no error checking is shown in the example */ struct NAME_REC{ /* Our file format */ char Name[7]; }nr; /* nr will be used as a buffer for converting strings to uppercase */ /* This is the data of the file we will create */ struct NAME_REC names[]={ "John", "Mary", "Robert", "Ann"}; Page -150- SCL1 Version 2.0 Reference Manual MoveFilePt2Offset main() { int handle,i,j; long fileptr,records; /* create file */ if(Buf2Disk("DEMO.FL",(char *)names,sizeof(names))) { printf("Error creating file\n"); exit(-1); } /* Open file for reading and writing */ OpenFile("DEMO.FL",&handle,DOS2_RW); /* number of records in file = file size / size of structure NAME_REC */ records=GetFileSize(handle)/sizeof(struct NAME_REC); /* read one record at a time while there are records */ for(;records > 0;--records) { /* save actual file pointer position */ fileptr=GetFilePt(handle); /* read data, file pointer is automatically moved to next record by DOS */ ReadFile(handle,(char *)&nr,sizeof(struct NAME_REC)); /* capitalize name */ strupr(nr.Name); /* move file pointer to original position */ MoveFilePt2Offset(handle,fileptr); /* write our data, pointer points again to next record */ WriteFile(handle,(char *)&nr,sizeof(struct NAME_REC)); } CloseFile(handle); system("type DEMO.FL"); } See also MoveFilePt. Page -151- SCL1 Version 2.0 Reference Manual OpenFile Function: OpenFile Purpose: Opens and existing file. Declaration: int OpenFile(char *Filename, int *Handle, char OMode); Returns: The return value is "0" if no error occurs or the DOS error code if an error occurs. (See Appendix "A", FILE FUNCTIONS, for more information). Parameters: Filename - pointer to filename (char). FHandle - pointer to variable that will hold DOS handle number (integer). OMode - One of several Open modes as defined in SCL1.H (char): DOS2_READ - For reading only. DOS2_WRITE - For writing. DOS2_RW - For reading and writing. Any of these modes can be used with DOS 2.0 or higher. The following can only be used with DOS 3.0 and higher. Here the Open Mode parameter is composed of three parts: the Inheritance Flag, that determines if child processes will inherit open files; the Sharing Mode, that determines if file can be shared by several processes; and the Access Mode that is similar to DOS 2.0 Open Mode. You must add the three flags to get the desired open mode. Inheritance Flag: DOS3_INHERIT - Child process inherit open files. DOS3_PRIVATE - No inheritance. Page -152- SCL1 Version 2.0 Reference Manual OpenFile Sharing mode: DOS3_COMP - Compatible with DOS 2.0 DOS3_DENY_RW - Deny read or write to other processes. DOS3_DENY_W - Deny write. DOS3_DENY_R - Deny read. DOS3_DENY_NONE - Deny none. Access mode: DOS3_READ, DOS3_WRITE, DOS3_RW are similar to DOS 2.0. See DOS 3.0 Technical Reference for more information. Example: #include <scl1.h> main() { int ErrorCode; if((ErrorCode=OpenFile("FILE.1",&Handle,DOS2_RW))) /* Open a file for reading & writing */ { . /* Error Routine */ . } } Page -153- SCL1 Version 2.0 Reference Manual PushCursor PopCursor Function: PushCursor PopCursor Purpose: Saves (PushCursor) or restores (PopCursor) the cursor size, shape and position. The maximum number of cursors that the function stack can hold is twenty. Declaration: int PushCursor(void); int PopCursor(void); Returns: Nothing. Parameters: None. Example: #include <scl1.h> main() { PushCursor(); . . . PopCursor(); } Page -154- SCL1 Version 2.0 Reference Manual PopMenu Function: PopMenu Purpose: Similar to Mouse Menu but draws the menu box and saves the area behind the menu box. If the left or right arrow is pressed the routine exits and returns a value indicating which arrow key has been pressed. Declaration: int PopMenu(int Color,int RColor, int HColor, struct PopMenuData *k); Returns: Return values are: "-3" if the right cursor key is pressed, "-2" if the left cursor key is pressed,"-1" if ESCAPE is pressed or the option number if an option key is pressed. Parameters: The menu information must be given as an array of structures as follows: struct PopMenuData{ int L1,C1,L2,C2; int NumberOption; char *WinBuffer; struct MenuOpt *Menust; }; where; L1 - upper row coordinate of the box used to enclose the pull-down menu (integer). C1 - left column coordinate of the box (integer). L2 - lower row coordinate of the box (integer). C2 - right column coordinate of the box (integer). NumberOptions - number of options of the pull-down menu (integer). WinBuffer - buffer to store the screen area used when popping out the pull-down menu. MenuOpt - pointer to the MenuOption structure corresponding to that pull-down menu. Page -155- SCL1 Version 2.0 Reference Manual PopMenu Example: #include <scl1.h> #include <scl1clor.h> struct MenuOpt Men1[]={ 2,5,"New ",'N', 3,5,"Open ",'O', 4,5,"Close ",'C', 5,5,"Save ",'S', 6,5,"Exit ",'E', }; struct PopMenuData pmd1[]={ 1,3,7,13, 5, WinBuf1, Men1, }; int Color1=WHITE_BLACK; int Color2=BLACK_WHITE; int Color3=BLACK_WHITE+HIGHLIGHT; main() { int Selection; Selection=PopMenu(Color1,Color2,Color3,pmd1); } Page -156- SCL1 Version 2.0 Reference Manual ReadFile Function: ReadFile Purpose: Reads number of bytes from a file Declaration: int ReadFile(int Handle,char *Buffer, unsigned int Bytes); Returns: The return value is "0" if no error occurs or the DOS error code if an error occurs. (See Appendix "A", FILE FUNCTIONS, for more information). Parameters: Handle - handle number given by DOS when you open or create a file (integer). Buffer - pointer to the buffer that will hold the data. Bytes - pointer to a variable that holds the number of bytes to read (unsigned integer). Example: #include <scl1.h> #define FILE_TOO_BIG 255 int File2Buf(char *FileName,char *Buffer,unsigned int * MaxSize) { int i,Handle; unsigned int Size; if(i=OpenFile(Filename,&Handle,DOS2_READ)) return(i); if((Size=GetFileSize(Handle)> *MaxSize) { CloseFile(Handle); return(FILE_TOO_BIG); } if(i=ReadFile(Handle,Buffer,Size)) { If(i>0) CloseFile(Handle); return(i); } *MaxSize=Size; return(CloseFile(Handle)); } Page -157- SCL1 Version 2.0 Reference Manual RemoveDir Function: RemoveDir Purpose: Removes a directory Declaration: int RemoveDir(char *Path); Returns: The return value is "0" if no error occurs or the DOS error code if an error occurs. (See Appendix "A", FILE FUNCTIONS, for more information). Parameters: Path - char pointer to directory string. Example: #include <scl1.h> main() { int ErrorCode; if((ErrorCode=RemoveDir("C:\\LETTERS"))) { . /* Error Routine */ . } } Page -158- SCL1 Version 2.0 Reference Manual RemoveExtension Function: RemoveExtension Purpose: Removes or deletes the extension of a filename. Declaration: char *RemoveExtension(char *Filename); Returns: The return value is a pointer to the filename buffer. Parameters: Filename - char pointer to filename. Example: #include <scl1.h> char Filename[13]="FILE.C"; main() { printf("%s\n",Filename); printf("%s\n",RemoveExtension(Filename)); } See also ChangeExtension and AddExtension Page -159- SCL1 Version 2.0 Reference Manual RenameFile Function: RenameFile Purpose: Renames or moves a file. Declaration: int RenameFile(char *OldName,char *NewName); Returns: The return value is "0" if no error occurs or the DOS error code if an error occurs. (See Appendix "A", FILE FUNCTIONS, for more information). Parameters: OldName - pointer to the old filename (char). NewName - pointer to the new filename (char). Example: #include <scl1.h> main() { int ErrorCode; if((ErrorCode=RenameFile("C:\\FILE.1","C:\\FILE.BAK"))) { . /* Error Routine */ . } } Page -160- SCL1 Version 2.0 Reference Manual ResetMouse Function: ResetMouse Purpose: Resets mouse to default condition (cursor hidden at screen center and Interrupt service routine disabled). Declaration: void ResetMouse(void); Returns: Nothing. Parameters: None Example: #include <scl1.h> main() { /* do we have a mouse? */ if(CheckMouse()) { /* Yes */ ResetMouse(); /* reset mouse */ SetMouseIsr(); /* initialize ISR */ ShowMouse(); /* cursor on */ } . . . ResetMouse(); /* reset mouse before exit */ } Page -161- SCL1 Version 2.0 Reference Manual ResetMouseCur Function: ResetMouseCur Purpose: Resets mouse cursor to a block character. Declaration: void ResetMouseCur(void); Returns: Nothing Parameters: None Example: include <scl1.h> #include <scl1clor.h> main() { GSSBox(WHITE_BLACK,0,0,0,24,79,1,0,0); InitMouse(IM_SHOW); if(MSE_MouseFl) { SetMouseCur('*'); WriteScreenLen(WHITE_BLACK+HIGHLIGHT,23,2,40,"Mouse cursor set to '*' character"); WaitTime(300); ResetMouseCur(); WriteScreenLen(WHITE_BLACK+HIGHLIGHT,23,2,40,"Mouse cursor reset to normal"); WaitTime(300); } else WriteScreenLen(WHITE_BLACK+HIGHLIGHT,23,2,40,"No mouse installed."); } Page -162- SCL1 Version 2.0 Reference Manual ScreenDump Function: ScreenDump Purpose: Displays a screendump array in the screen. The screendump array consists of characters followed by its color attribute byte, terminated with a "0". Declaration: void ScreenDump(int Row, int Column, char *Array); Returns: Nothing Parameters: Row - row position for the array display (integer). Column - column position for array display (integer). Array - pointer to the array buffer (char). Example: #include <scl1.h> char Array[]={'A',7,'B',0x70,\n,'C',0x70,'D',7,0}; main() { /* Each character is followed by its color attribute, a \n can be used to indicate end of lines and a "0" must be used to indicate the end of the array */ ScreenDump(10,10,Array); /* Write at line 10, column 10 */ GetKey(); ChangeDumpColor(0x70,7,Array); ScreenDump(10,10,Array); /* Write at line 10, column 10 */ /* Change all character attributes 0x17 to 7 */ } Notes: The array must be null terminated, \n is used to indicate end of lines. See also ChangeDumpColor. Page -163- SCL1 Version 2.0 Reference Manual ScrollDown Function: ScrollDown Purpose: Scrolls down a screen area. Declaration: void ScrollDown(int Color, int UpperRow, int LeftCol, int LowerRow, int RightCol, int Scroll); Returns: Nothing Parameters: Color - color attribute of the area to be scrolled (integer). UpperRow - upper row coordinate of the area to be scrolled (integer). LeftCol - left column coordinate of the area to be scrolled (integer). LowerRow - lower row coordinate of the area to be scrolled (integer). RightCol - right column coordinate of the area to be scrolled (integer). Scroll - number of lines to scroll, if this variable is set to "0" the whole window is cleared (integer). Example: ScrollDown(Color1,18,0,24,79,1); Page -164- SCL1 Version 2.0 Reference Manual ScrollList Function: ScrollList Purpose: Displays a list of items enclosed in a box. Only the number of items desired are displayed. The function permits to scroll through the items using the arrow keys or the mouse. Pressing the ENTER key or clicking the mouse in a highlighted item selects the desired item. Declaration: int ScrollList(int NColor, int RColor, int Row, int Col, int Lines,char **p); Returns: The return value is the selected item's number or "-1" if the ESC key is pressed. Parameters: The scroll list information must be given in a null terminated char pointer array as follows: char * ScrollDat[] The parameters passed to the function are: NColor - color attribute for the normal display of items (integer). RColor - color attribute for the highlighted item (integer). Row - row position for the display of the first item of the scroll list (integer). Col - column position for the display of the first item of the scroll list (integer). Lines - number of lines to display in the box (integer). p - char pointer to the ScrollList structure. Page -165- SCL1 Version 2.0 Reference Manual ScrollList Example: #include <scl1.h> #include <scl1clor.h> int Color1=WHITE_BLACK; int Color2=BLACK_WHITE; /* ScrollList pointer structure */ char *Slist[]={ "Copy File ", "Sort File ", "Move File ", "Merge Files ", "Delete File ", "Tag File ", "Erase File ", "Append Files", "Browse File ", "Insert File ", 0}; main() { int Selection; Selection=ScrollList(Color1,Color2,5,40,5,(int*)Slist); } Page -166- SCL1 Version 2.0 Reference Manual ScrollUp Function: ScrollUp Purpose: Scrolls up a screen area. Declaration: void ScrollUp(int Color, int UpperRow, int LeftCol, int LowerRow,int RightCol, int Scroll); Returns: Nothing Parameters: Color - color attribute of the area to be scrolled (integer). UpperRow - upper row coordinate of the area to be scrolled (integer). LeftCol - left column coordinate of the area to be scrolled (integer). LowerRow - lower row coordinate of the area to be scrolled (integer). RightCol - right column coordinate of the area to be scrolled (integer). Scroll - number of lines to scroll, if this variable is set to "0" the whole window is cleared. Example: ScrollUp(Color1,18,0,24,79,1); Page -167- SCL1 Version 2.0 Reference Manual ScrollWindow Function: ScrollWindow Purpose: Displays a window with a list of items. If the list is larger than the window, or if a item's length is larger than the display width, you can scroll the display area both horizontally and vertically to show all the information. The window can have scroll bars in both the right side and the bottom to show the relative position of the text within the window. The function permits you to scroll through the items using the cursor keys or the mouse. Pressing the SPACEBAR or clicking the mouse after pointing to an item tags or untags the desired item. This is a dialog type function. To select an item press the ENTER key or double click the mouse after pointing to the item. Declaration: int ScrollWindow(int Message,SWData *p,...) Returns: This is a dialog type function. See Appendix "E" for a description of the general operation of these functions. The return value is a message described in the Messages section. Parameters: The scroll window information must be given in a structure defined as type SWData. The structure elements are as follows: SWData type structure: typedef struct{ int NColor; int RColor; int UpperRow; int LeftCol; int LowerRow; int RightCol; int FrameType; int ScrollBar; int BarColor; char **Array; char *TagArray; int TagColor; char *Title; int TitleColor; unsigned int *ExitKeys; Page -168- SCL1 Version 2.0 Reference Manual ScrollWindow unsigned int Lines; unsigned int Length; unsigned int TopLine; unsigned int Position; unsigned int FirstCol; int OldVBlock; int OldHBlock; int WindowLines; int WindowCols; int VScroll; int HScroll; unsigned int EventInfo; }SWData; where; NColor - color attribute for normal display (integer). RColor - color attributes for reversed display (integer). UpperRow - upper row coordinate of the window (integer). LeftCol - left column coordinate of the window (integer). LowerRow - lower row coordinate of the window (integer). RightCol - right column coordinate of the window (integer). FrameType - any of the frame types that can be used with the Box or GSSbox functions (integer). ScrollBar - a flag to signal the function to draw scroll bars to indicate the relative position of the cursor within the array length (integer). BarColor - color attributes for the scroll bars (integer). Array - pointer to a null terminated array of pointers to be displayed. TagArray - an array that holds which item has been tagged. If a null pointer is specified the function will not permit tagging. An array element value of "0" and "1" indicate the status for untagged and tagged (char). Page -169- SCL1 Version 2.0 Reference Manual ScrollWindow TagColor - color attributes to be used for displaying a tagged item (integer). Title - char pointer to text to be displayed in the window's top row as a title. TitleColor - color attributes for the title's display (integer). ExitKeys - an array of keys defined to exit the function (unsigned integer). Lines - structure element (used internally) that holds the quantity of items in the array (unsigned integer). Length - structure element (used internally) that holds the length of the longest element in the ScrollWindow array (unsigned integer). TopLine - structure element (used internally) that holds the element number that is being displayed in the first line of the window (unsigned integer). Position - structure element (used internally) that holds the active position of the display (unsigned integer). Note this element should not be modified by the calling program. FirstCol - structure element (used internally) that holds the horizontal offset of the window. If there is no horizontal scroll, its value is "0". When there is scroll the value will be the number of columns to the left of the first column displayed (unsigned integer). OldVHBlock - structure element (used internally) that holds the position of the vertical relative position indicating scroll bar block (integer). OldVHBlock - structure element (used internally) that holds the position of the horizontal relative position indicating scroll bar block (integer). WindowLines - structure element (used internally) that holds the number of lines in the List Window (integer). Page -170- SCL1 Version 2.0 Reference Manual ScrollWindow WindowCols - structure element (used internally) that holds the number of columns in the List Window (integer). VScroll - structure element (used internally) that keeps track if vertical scroll is required (integer). HScroll - structure element (used internally) that keeps track if horizontal scroll is required (integer). EventInfo - information about the keys that have been pressed (unsigned integer). Messages: The messages that can be sent to the ScrollWindow function are: SW_INIT - Initialize the SWData structure to its default values. The default values are: NColor - set to white characters in a black background or the normal color defined by calling SetDialogColors. RColor - set to black characters in a white background or the reversed color defined by calling SetDialogColors. LowerRow - one row less than the screen length. RightCol - one column less than the screen width. FrameType - set to frame type "1" (single line). ScrollBar - set to draw scroll bars. BarColor - set to black characters in a white background or the reversed color defined by calling SetDialogColors. Page -171- SCL1 Version 2.0 Reference Manual ScrollWindow TagColor - set to black characters in a white background or the reversed color defined by calling SetDialogColors. TitleColor - set to white characters in a black background or the normal color defined by calling SetDialogColors. OldVBlock - set to "1". OldHBlock - set to "1". SW_DRAW - display the Scroll Window with the current information. SW_WRITE - write the items to the screen. SW_ACTIVE - browse through the displayed items and permit the selection or tagging of them using the cursor movement keys as follows: Key action Up Arrow cursor one item up. Down Arrow cursor one item down. END cursor to end of file list. HOME cursor to beginning of list. Page Up cursor one screen up. Page Down cursor one screen down. SW_DRAW_BORDER - draw the Scroll Window's border. SW_POSITION_BEGIN - move cursor to the first item. SW_POSITION_END - move cursor to the last item. SW_POSITION_UP - move cursor to the previous item. SW_POSITION_DOWN - move cursor to the next item. SW_SET_POSITION - move cursor to a specific item. The item number is passed as a parameter. SW_CLS - clear the list window. Page -172- SCL1 Version 2.0 Reference Manual ScrollWindow SW_CHECK_MOUSE - check if the mouse has been clicked after pointing to the area defined by the function. SW_UWRITE - recalculate all the internal variables but do not write the Scroll Window unless the display contents has changed. SW_RESET - when this message is sent the position variables are reset to the default value. If the exit keys have not been defined they are set to the default exit keys. The messages returned by ScrollWindow are: SW_NULL_ARRAY - no item array has been defined. SW_OK - the requested action has been performed. SW_EXIT_KEY - a defined exit key has been pressed. SW_MOUSE_EVENT - the mouse has been clicked but it has not been pointed to the area defined by the function. SW_BUFFER_END - you have requested to move the cursor passed the last item. SW_BUFFER_BEGIN - you have requested to move the cursor up and you have the first item active. SW_ILLEGAL_KEY - an undefined key has been pressed. SW_ILLEGAL_POSITION - you have requested to move the cursor to an invalid position. SW_NEW_POSITION - the cursor position has been updated. SW_MOUSE_SELECT - one of the elements have been selected by double clicking the mouse. SW_MY_MOUSE - response to a SW_CHECK_MOUSE message if the mouse has been clicked after pointing to the area defined by the function. Page -173- SCL1 Version 2.0 Reference Manual ScrollWindow SW_NEW_MOUSEPOS - you have moved the cursor by clicking the mouse after pointing to an item. SW_BLOCK_MARK - this message is returned when you have marked a series of items by dragging you mouse after clicking at an item. Example: #include <scl1.h> #include <scl1clor.h> #include <scl1keys.h> int Color1=WHITE_BLACK; char *Info={"", " BigCursor - Changes the cursor size to a block.", "", " Center - Centers a string horizontally.", "", " Cls - Clears a screen area.", "", " CursorOff - Turns the cursor off.", "", " CursorOn - Turns the cursor on (cursor visible).", "", " DrawItemList - Draws an item list to the screen.", "", " GetCurLine - Returns the current cursor row position.", "", " GetCurSize - Returns the current cursor size.", "", " ScrollUp - Scrolls up a screen area.", "", " SetCurPos - Sets the cursor position.", "", " SetCurSize - Sets the cursor size.", "", " SetVideoMode - Sets the video mode.", "", " SetVideoPage - Sets the video page.", "", " SetVideo25 - Sets the display mode to 25 lines.", "", " Shadow - Draws a shadow effect to a screen area.", "", Page -174- SCL1 Version 2.0 Reference Manual ScrollWindow " Video - Detects if the video adapter in use is", " either Monochrome, CGA or EGA.", "", " WriteCharBlock - Writes a block of characters.", "", " WriteOffset - Writes a character at a given offset.", "", " Window - Saves, clears and restores a window.", ,0}; unsigned int ExitK[]={ESC,ENTER,0}; main { int i; SWData sw; /* Use the default Scroll Window structure */ CursorOff(); /* Turn of cursor */ InitMouse(IM_SHOW); Cls(Color1,CLS_ALL); ScrollWindow(SW_INIT,&sw); /* Initialize Scroll Window */ sw.UpperRow=2; /* Change default window size */ sw.LeftCol=4; sw.LowerRow=22; sw.RightCol=75; sw.NColor=0x70; /* Change default color */ sw.RColor=0x7f; /* Do not show scroll bar */ sw.ExitKeys=ExitK; sw.Array=Info; sw.Title="[ Information ]"; sw.TitleColor=0x70; SetShadowColor(8); /* We want an Xor shadow */ Shadow(0,2,4,22,75); /* Around Scroll Window */ ScrollWindow(SW_DRAW,&sw); /* Now, draw the Scroll Window */ do /* Browse window until an exit key is pressed*/ { i=ScrollWindow(SW_ACTIVE,&sw); }while(i!=SW_EXIT_KEY && i!=SW_MOUSE_EVENT); CursorOn(); } Page -175- SCL1 Version 2.0 Reference Manual Select Function: Select Purpose: Will permit the display of various options and let the user to select one of them. To move among options the user can use the arrow keys. A selection can be made by clicking the left mouse button after pointing to the desired option or by pressing a key defined as an exit key. The active option will be displayed with a check mark between parenthesis (√). This is a dialog type function that can either be used alone or as one of the field types for the fields option. Declaration: int Select(int Message,SData1 *sd1,SData2 *sd2) Returns: This is a dialog type function. See Appendix "E" for a description of the general operation of these functions. The return value is a message described in the Messages section. Parameters: The options must be passed as a null terminated array of structures of the type SData1, one array element for each select option: typedef struct{ int Row; int Col; char *String; }SData1; where, Row - row position where the option is displayed (integer). Col - column position where the option is displayed (integer). String - char pointer to the text used to identify the option. Page -176- SCL1 Version 2.0 Reference Manual Select The general information about the Select options are included in a structure type SData2, as follows: typedef struct{ int Color; int PRow; int PCol; char *Prompt; unsigned int *ExitKeys; int Options; int Position; unsigned int EventInfo; }SData2; where, Color - color attributes for the display of the select options (integer). PRow - row position where to display an optional prompt or select options title (integer). PCol - column position where to display an optional prompt or select options title (integer). Prompt - char pointer to an optional prompt or select options title. ExitKeys - array of keys defined as exit keys (unsigned integer). Options - number of options available (integer). Position - default selection (integer). EventInfo - this structure element will hold the last illegal or exit key pressed (unsigned integer). Messages: The messages that can be sent to the Select are: S_INIT - initialize the SData2 structure to NULL (the SData1 structure must be initialized with the position and text information) and set the following default values: Page -177- SCL1 Version 2.0 Reference Manual Select Color - set to black characters in a white background or the reversed color defined by calling SetDialogColors. ExitKeys - ENTER, ESC, TAB and SHIFT TAB. S_DRAW - draws the Select display. S_ACTIVE - activates the function. S_CHECK_MOUSE - check if the mouse has been clicked after pointing to the area defined by the function. S_RESET - when this message is sent the position variables are reset to the default value. If the exit keys have not been defined they are set to the default exit keys. The following messages can be returned by Select: S_NULL_ARRAY - no select item array has been defined. S_OK - action requested was performed. S_EXIT_KEY - a key defined as an exit key has been pressed. S_MOUSE_EVENT - the mouse has been clicked but it has not been pointed to the area defined by the function. S_ILLEGAL_KEY - an illegal key has been pressed. S_NEW_POSITION - the cursor position has been updated. S_MY_MOUSE - response to a S_CHECK_MOUSE message if the mouse has been clicked after pointing to the area defined by the function. Page -178- SCL1 Version 2.0 Reference Manual Select Example: #include <scl1.h> #include <scl1keys.h> #include <scl1clor.h> unsigned int ExitKeys[]={ESC,ENTER,0}; SData1 sd1[]={ 12,35,"Male", 13,35,"Female", 0}; SData2 sd2={WHITE_BLACK,10,32,"Enter your sex:",ExitKeys,0,0,0}; main() { int Mess; InitVideo(); Select(S_RESET,sd1,&sd2); Select(S_DRAW,sd1,&sd2); do { Mess=Select(S_ACTIVE,sd1,&sd2); }while(Mess!=S_EXIT_KEY); } Page -179- SCL1 Version 2.0 Reference Manual SetCurPos Function: SetCurPos Purpose: Sets the cursor position. Declaration: void SetCurPos(int Row, int Col); Returns: Nothing Parameters: Row - the desired row position coordinate (integer). Col - the desired column position coordinate (integer). Example: #include <scl1.h> #include <scl1clor.h> main() { InitVideo(); SetCurPos(10,20); printf("Cursor was moved to position 10,20"); WaitTime(200); SetCurPos(20,40); printf("Cursor was moved to position 20,40"); WaitTime(200); SetCurPos(0,0); printf("Cursor was moved to position 0,0"); } Page -180- SCL1 Version 2.0 Reference Manual SetCurSize Function: SetCurSize Purpose: Sets the cursor size. Declaration: void SetCurSize(int CursorSize); Returns: Nothing Parameters: CursorSize - the desired cursor size, an unsigned integer value that contains both the scan start and end line. To determine this value use the following formula: Size = StartLine*256+EndLine. The start and end lines for MONOCHROME monitors are from "0" to "13" and for COLOR monitors from "0" to "7". Example: #include <scl1.h> #include <scl1clor.h> main() { int topline,bottomline; InitVideo(); topline=0; if(Video()==COLOR) bottomline=7; else bottomline=13; printf("\nYour cursor will start growing: "); for(topline=bottomline-1;topline > 0;--topline) { SetCurSize(topline * 256 + bottomline); WaitTime(50); } printf("\nYour cursor will now return to normal: "); for(;topline < bottomline;++topline) { SetCurSize(topline * 256 + bottomline); WaitTime(50); } } Page -181- SCL1 Version 2.0 Reference Manual SetDialogColor Function: SetDialogColor Purpose: Lets you define the colors for the dialog type functions. Sets global variables D_NColor, which holds the normal color attributes, D_RColor, which holds the reversed color attributes and D_HColor, which holds the highlight color attributes. If this function is not called the variables will contain the following default values; D_NColor=0x7, D_RColor=0x70 and D_HColor=0x0f. Declaration: void SetDialogColor(int NColor,int RColor, int HColor); Returns: Nothing Parameters: NColor - normal color attributes for the dialog functions (integer). RColor - reversed color attributes for the dialog functions (integer). HColor - highlight color attributes for the dialog functions (integer). Example: #include <scl1.h> #include <scl1clor.h> int Color1=WHITE_BLUE; int Color2=BLUE_WHITE; int Color3=WHITE_BLUE+HIGHLIGHT; main() { SetDialogColor(Color1,Color2,Color3); . . /* Will set the color attributes for subsequent calls to dialog type functions to Color1, Color3 and Color3. */ } Page -182- SCL1 Version 2.0 Reference Manual SetErrorBoxColor Function: SetErrorBoxColor Purpose: Lets you define the color for the Error Box function. Declaration: void SetErrorBoxColor(int UColor) Returns: Nothing Parameters: UColor - color attribute for Error Box messages (integer). Example: #include <scl1.h> #include <scl1clor.h> int Color1=RED_WHITE; main() { SetErrorBoxColor(Color1); . . /* Will set a color for subsequent calls to the Error Box function to Color1. */ } See also ErroBox. Page -183- SCL1 Version 2.0 Reference Manual SetFileMode Function: SetFileMode Purpose: Sets a file's attributes (system, hidden, read only, etc.). Declaration: int SetFileMode(char *Filename, int NewMode); Returns: The return value is "0" if no error occurs or the DOS error code if an error occurs. (See Appendix "A", FILE FUNCTIONS, for more information). Parameters: A mask has been defined in SCL1.H (see GetFileMode): They can be ored to "add" several attributes. Example: #include <scl1.h> char Filename[]="FILE.1"; main() { int handle; unsigned int FMode; if(CreateFile(Filename,&handle,F_ARCHIVE)) exit(-1); if(GetFileMode(Filename,&FMode)) exit(-1); PrintFMode(FMode); if(SetFileMode(Filename,F_READ_ONLY | F_SYSTEM | F_HIDDEN)) exit(-1); if(GetFileMode(Filename,&FMode)) exit(-1); PrintFMode(FMode); if(SetFileMode(Filename,F_ARCHIVE)) exit(-1); DeleteFile(Filename); } Page -184- SCL1 Version 2.0 Reference Manual SetFileMode PrintFMode(unsigned int FMode) { printf("\nFile attributtes:\n\n"); if(FMode & F_READ_ONLY) printf("\tRead Only\n"); if(FMode & F_HIDDEN) printf("\tHidden\n"); if(FMode & F_SYSTEM) printf("\tSystem\n"); if(FMode & F_ARCHIVE) printf("\tArchive\n"); } Page -185- SCL1 Version 2.0 Reference Manual SetHorLimit Function: SetHorLimit Purpose: Sets the minimum and maximum mouse horizontal coordinates. Declaration: void SetHorLimit(int Minimum,int Maximum); Returns: Nothing Parameters: Minimum - integer value indicating the minimum horizontal coordinate. Maximum - integer value indicating the maximum horizontal coordinate. Example: #include <scl1.h> #include <scl1clor.h> main() { InitMouse(IM_SHOW); if(MSE_MouseFl) { SetHorLimit(39,39); printf("Mouse movement has been limited to column 39, click mouse to exit\n"); while(!MSE_LPress); } else printf("No mouse installed\n"); } See also SetVerLimit. Page -186- SCL1 Version 2.0 Reference Manual SetInt24Colors Function: SetInt24Colors Purpose: Lets you define the color for the error display box used by the TrapInt24 function. Declaration: void SetInt24Colors(int NColor, int RColor); Returns: Nothing Parameters: NColor - normal color attribute for the TrapInt24 error display (integer). RColor - reversed color attribute for the TrapInt24 error display (integer). Example: #include <scl1.h> #include <scl1clor.h> int Color1=WHITE_BLACK; int Color2=BLACK_WHITE; main() { SetInt24Colors(Color1,Color2); /* Will set the colors for calls to the TrapInt24 function to Color1 and Color2. */ . . } Page -187- SCL1 Version 2.0 Reference Manual SetMouseCur Function: SetMouseCur Purpose: Sets mouse cursor. Any valid character can be used as the mouse cursor. Declaration: void SetMouseCur(int Character); Returns: Nothing Parameters: Character - any valid character to be used as the mouse cursor (integer). Example: #include <scl1.h> #include <scl1clor.h> main() { GSSBox(WHITE_BLACK,0,0,0,24,79,1,0,0); InitMouse(IM_SHOW); if(MSE_MouseFl) { SetMouseCur('*'); WriteScreenLen(WHITE_BLACK+HIGHLIGHT,23,2,40,"Mouse cursor set to '*' character"); WaitTime(300); ResetMouseCur(); WriteScreenLen(WHITE_BLACK+HIGHLIGHT,23,2,40,"Mouse cursor reset to normal"); WaitTime(300); } else WriteScreenLen(WHITE_BLACK+HIGHLIGHT,23,2,40,"No mouse installed."); } Page -188- SCL1 Version 2.0 Reference Manual SetMouseIsr Function: SetMouseIsr Purpose: Sets an Interrupt service routine that is called whenever the mouse moves or any of its buttons is pressed or released. Declaration: void SetMouseIsr(void); Returns: Nothing The following variables are set according to mouse status: MSE_LPress is set to "1" when the left button is pressed. MSE_LpX and MSE_LpY are set to the X and Y position when the left button is pressed. MSE_LRel, MSE_LrX and MSE_LrY are set to the X and Y position when the left button is released. MSE_RPress is set to "1" when the right button is pressed. MSE_RpX and MSE_RpY are set to the X and Y position when the right button is pressed. MSE_RRel, MSE_RrX, and MSE_RrY are set to the X and Y position when the right button is released. MSE_Move is set to "1" when the mouse is moved. MSE_MoveX and MSE_MoveY hold the actual X and Y mouse position. MSE_DoubleClick is set to "1" when you double click the left mouse button. MSE_MouseFl is set to "1" when the mouse driver is present. Before ending your program you must Reset the mouse using ResetMouse or disable the interrupt service routine using DisableMouseIsr or ResetMouse. Page -189- SCL1 Version 2.0 Reference Manual SetMouseIsr Example: #include <scl1.h> main() { /* do we have a mouse? */ if(CheckMouse()) { /* Yes */ ResetMouse(); /* reset mouse */ SetMouseIsr(); /* initialize ISR */ ShowMouse(); /* cursor on */ } . . . ResetMouse(); /* reset mouse before exit */ } See also InitMouse Page -190- SCL1 Version 2.0 Reference Manual SetMousePos Function: SetMousePos Purpose: Sets the mouse cursor position. Declaration: void SetMousePos(int X, int Y); Returns: Nothing Parameters: X - integer value indicating the horizontal coordinate. Y - integer value indicating the vertical coordinate. Example: #include <scl1.h> #include <scl1clor.h> main() { GSSBox(WHITE_BLACK,0,0,0,24,79,1,0,0); InitMouse(IM_SHOW); if(MSE_MouseFl) { SetMousePos(1,1); WriteScreen(WHITE_BLACK+HIGHLIGHT,23,2,"Mouse cursor position (X,Y) = 1,1"); WaitTime(200); SetMousePos(39,12); WriteScreen(WHITE_BLACK+HIGHLIGHT,23,2,"Mouse cursor position (X,Y) = 39,12"); WaitTime(200); SetMousePos(78,23); WriteScreen(WHITE_BLACK+HIGHLIGHT,23,2,"Mouse cursor position (X,Y) = 78,23"); WaitTime(200); } else WriteScreen(WHITE_BLACK+HIGHLIGHT,23,2,"No mouse installed."); } Page -191- SCL1 Version 2.0 Reference Manual SetShadowColor Function: SetShadowColor Purpose: Sets the shadow color for subsequent shadow effects drawn. When calling functions that support a shadow effect, this function will permit you to select the color to be XOR'ed with the background color to produce a pleasing effect. You must specify the color in these functions as "0". If you prefer a solid color for the shadow effect you should specify it as a color parameter when calling the function. Declaration: void SetShadowColor(int Color); Returns: Nothing Parameters: Color - color attribute for the shadow effect (to be XOR'ed with the background color) (integer). Example: #include <scl1.h> #include <scl1clor.h> main() { FillBlock(WHITE_BLACK+HIGHLIGHT,0,0,24,79,'X'); GSSBox(WHITE_BLACK+HIGHLIGHT,0,5,20,20,60,1,0,0); SetShadowColor(BLACK_WHITE); Shadow(0,5,20,20,60); GetKey(); SetShadowColor(WHITE_BLACK); Shadow(0,5,20,20,60); GetKey(); SetShadowColor(BLACK_BLACK+HIGHLIGHT); Shadow(0,5,20,20,60); } Page -192- SCL1 Version 2.0 Reference Manual SetUserBox Function: SetUserBox Purpose: Lets you define a different frame type than those available for the Box and GSSBox functions. Declaration: void SetUserBox(int UpperLeft,int UpperRight, int LowerLeft,int LowerRight,int UpperSide, int BottomSide,int LeftSide,int RightSide); Returns: Nothing Parameters: UpperLeft - upper left corner character of the box frame (integer). UpperRight - upper right corner character of the box frame (integer). LowerLeft - lower left corner character of the box frame (integer). LowerRight - lower right corner character of the box frame (integer). UpperSide - characters to be used for drawing the upper border of the box frame (integer). BottomSide - characters to be used for drawing the bottom border of the box frame (integer). LeftSide - characters to be used for drawing the left border of the box frame (integer). RightSide - characters to be used for drawing the right border of the box frame (integer). Page -193- SCL1 Version 2.0 Reference Manual SetUserBox Example: #include <scl1.h> #include <scl1clor.h> main() { SetUserBox(21,21,21,21,21,21,21,21); GSSBox(BLACK_WHITE,12,2,2,22,77,1,0,0); } Page -194- SCL1 Version 2.0 Reference Manual SetUserBoxLine Function: SetUserBoxLine Purpose: Lets you define a line type for drawing lines inside boxes that use lines defined by using the SetUserBox function. Declaration: void SetUserBoxLine(int HLeft,int HRight, int VUpper,int VLower); Returns: Nothing Parameters: HLeft - horizontal left terminating character of the line (integer). HRight - horizontal right terminating character of the line (integer). VUpper - vertical upper terminating character of the line (integer). VLower - vertical lower terminating character of the line (integer). Example: #include (scl1.h> main() { SetUserBoxLine(201,188,200,189,205,205,186,186); . . /* Will set a user type frame to double line, exactly as defined in standard frame type 0 of the Box and GSSBox functions*/ } Page -195- SCL1 Version 2.0 Reference Manual SetVerLimit Function: SetVerLimit Purpose: Sets the mouse minimum and maximum vertical coordinates. Declaration: void SetVerLimit(int Minimum,int Maximum); Returns: Nothing Parameters: Minimum - integer value indicating the minimum vertical coordinate. Maximum - integer value indicating the maximum vertical coordinate. Example: #include <scl1.h> #include <scl1clor.h> main() { InitMouse(IM_SHOW); if(MSE_MouseFl) { SetVerLimit(11,11); printf("Mouse movement has been limited to line 11, click mouse to exit\n"); while(!MSE_LPress); } else printf("No mouse installed\n"); } See also SetHorLimit. Page -196- SCL1 Version 2.0 Reference Manual SetVideoMode Function: SetVideoMode Purpose: Sets the desired video mode. See the BIOS reference manual for the available video modes. SCL1 only supports the 40 and 80 column text modes. Declaration: void SetVideoMode(int NewMode); Returns: Nothing Parameters: NewMode - video mode as defined by the DOS (integer). Example: #include <scl1.h> /* Initializes Video mode to mode 3 in case of color, EGA or VGA or to mode 7 in case mono */ void InitVideo(void) { Video(); if(VC_Segment==COLOR) SetVideoMode(3); else SetVideoMode(7); } Page -197- SCL1 Version 2.0 Reference Manual SetVideoPage Function: SetVideoPage Purpose: Sets the active video page. See the BIOS reference manual for the available video pages. Declaration: void SetVideoPage(int NewPage); Returns: Nothing Parameters: NewPage - video page (supported by your display adapter) as defined in the BIOS (integer). Example: #include <scl1.h> #include <scl1clor.h> main() { Video(); if(VC_Monitor==VC_MDA) { printf("Monochrome monitors do not support video pages\n"); exit(-1); } Cls(WHITE_BLACK,CLS_ALL); WriteScreen(WHITE_BLACK,10,35,"Video page 0"); WaitTime(100); SetVideoPage(1); Cls(BLACK_WHITE,CLS_ALL); WriteScreen(BLACK_WHITE,10,35,"Video page 1"); WaitTime(100); SetVideoPage(0); WaitTime(100); SetVideoPage(1); WaitTime(100); SetVideoPage(0); } Page -198- SCL1 Version 2.0 Reference Manual SetVideo4350 Setvideo25 Function: SetVideo4350 SetVideo25 Purpose: The SetVideo4350 function sets the display mode to 43 lines (EGA display adapters) or to the 50 lines (VGA display adapters). The SetVideo25 function resets the display mode to 25 lines. Declaration: void SetVideo4350(void); void SetVideo25(); Returns: Nothing Parameters: None Example: #include <scl1.h> #include <scl1clor.h> main() { Video(); if(VC_Monitor != VC_VGA && VC_Monitor != VC_EGA) { printf("Video system does not supports 43/50 lines video mode\n"); exit(-1); } SetVideo4350(); FillBlock(WHITE_BLACK,0,0,VC_Lines-1,79,'*'); MessageOn(BLACK_WHITE,"43/50 lines Video Mode\n press any key..."); GetKey(); SetVideo25(); FillBlock(WHITE_BLACK,0,0,VC_Lines-1,79,'*'); MessageOn(BLACK_WHITE,"25 lines Video Mode\npress any key..."); GetKey(); Cls(7,CLS_ALL); } Page -199- SCL1 Version 2.0 Reference Manual Shadow Function: Shadow Purpose: Draws a shadow to a screen area. Declaration: void Shadow(int Color,int UpperRow, int LeftCol, int LowerRow, int RightCol); Returns: Nothing Parameters: Color - color attribute of the desired shadow effect. If a value of "0" is specified the shadow effect is XOR'ed. to the screen area. You can use the SetShadowColor function to specify the color to be XOR'ed with the foreground (integer). UpperRow - upper row coordinate of the area (integer). LeftCol - left column coordinate of the area (integer). LowerRow - lower row coordinate of the area (integer). RightCol - right column coordinate of the area (integer). Example: #include <scl1.h> #include <scl1clor.h> main() { Box(WHITE_BLACK,0,10,10,20,70); Shadow(BLACK_WHITE,10,10,20,70); } Page -200- SCL1 Version 2.0 Reference Manual ShowMouse Function: ShowMouse Purpose: Makes mouse cursor visible. Declaration: void ShowMouse(void); Returns: Nothing Parameters: None Example: #include <scl1.h> main() { InitMouse(IM_SHOW); /* initialize mouse, turn cursor on */ if(MSE_MouseFl) { printf("We have a mouse, click the left button to turn mouse cursor off.\n"); WaitKeyMouse(); HideMouse(); printf("Click again to turn mouse cursor on.\n"); WaitKeyMouse(); ShowMouse(); printf("Click to exit.\n"); WaitKeyMouse(); } else printf("We don't have a mouse\n"); } Page -201- SCL1 Version 2.0 Reference Manual SortPointers Function: SortPointers Purpose: Sorts a null terminated array of char pointers that hold the address of strings according in alphabetical order. Declaration: void SortPointers(char *p[]); Returns: Nothing Parameters: p - pointer to a null terminated array of char pointers. Example: #include <scl1.h> char *names[]={ "Mozart", "Villa-Lobos", "Chopin", "Bach", "Schubert", "Debussy", "Albeniz", "Beethoven", "Falla", 0, }; main() { int i; SortPointers(names); for(i=0;names[i];++i) printf("%s\n",names[i]); } Page -202- SCL1 Version 2.0 Reference Manual Sound Function: Sound Purpose: Sets a sound frequency. Declaration: void Sound(int Freq); Returns: Nothing Parameters: Freq - the desired frequency in hertz (integer). Example: #include <scl1.h> main() { SoundOn(); for(Freq=400;Freq<2000;Freq+=100) { Sound(Freq); WaitTime(10); } SoundOff(); } See the note definitions in header file SCL1SND.H. Page -203- SCL1 Version 2.0 Reference Manual SoundOff SoundOn Function: SoundOff SoundOn Purpose: Turns the speaker Off or On. Declaration: void SoundOff(void); void SoundOn(void); Returns: Nothing Parameters: None Example: #include <scl1.h> main() { SoundOn(); for(Freq=400;Freq<2000;Freq+=100) { Sound(Freq); WaitTime(10); } SoundOff(); } See the note definitions in header file SCL1SND.H. Page -204- SCL1 Version 2.0 Reference Manual StopWatch Function: StopWatch Purpose: Measures elapsed time in 1/100 seconds Declaration: long StopWatch(int Function); Returns: Elapsed Time between calls to the function. The stop watch is started by calling the function with the SW_START parameter. When the stop watch is stopped by calling the function with the SW_STOP parameter it returns the elapsed time. Parameters: See the above explanation. Example: #include <scl1.h> main() { unsigned int i; register unsigned int j; long t; StopWatch(SW_START); for(i=0;i < 65535;++i); t=StopWatch(SW_STOP); printf("Your computer needs %li/100 of a second to count from 1 to 65535.\n",t); StopWatch(SW_START); for(j=0;j < 65535;++j); t=StopWatch(SW_STOP); printf("This time can be reduced to %li/100 of a second by using a register variable.\n",t); } Page -205- SCL1 Version 2.0 Reference Manual TagItem Function: TagItem Purpose: Will permit the display of one item and permits the user to tag or untag it. To tag or untag an item, move the cursor to the tag indicator (a pair of parenthesis) and press the SPACEBAR. An item can also be tagged or untagged by clicking the left mouse button after pointing it. An item that has been tagged will be displayed with a check mark (√) between the tag indicating parenthesis. This is a dialog type function that can either be used alone or as one of the field types for the fields option. Declaration: int TagItem(int Message, TIData *tg) Returns: This is a dialog type function. See Appendix "E" for a description of the general operation of these functions. The return value is a message described in the Messages section. Parameters: The TagItem parameters must be passed to a structure of the type SData1 as follows. Structure type TIData. typedef struct{ int Color; int Row; int Col; int TagFl; char *String; unsigned int *ExitKeys; unsigned int EventInfo; }TIData; where, Color - color attributes for the display of the TagItem (integer). Row - row position where the TagItem is displayed (integer). Col - column position where the TagItem is displayed (integer). Page -206- SCL1 Version 2.0 Reference Manual TagItem String - char pointer to the text used to identify the TagItem. TagFl - a flag that will have a value of "1" if the item has been tagged and a value of "0" if it has not been tagged (integer). ExitKeys - array of keys defined as exit keys (unsigned integer). EventInfo - this structure element will hold the last key pressed (unsigned integer). Messages: The following messages can be sent to Select: TI_INIT - initialize the TIData structure to NULL and set the following default values: Color - set to white characters in a black background or the normal color defined by calling SetDialogColors. TI_DRAW - display the Tag Item with the current information. TI_ACTIVE - take control to tag an item. TI_CHECK_MOUSE - check if the mouse has been clicked after pointing to the area defined by the function. TI_RESET - when this message is sent the position variables are reset to the default value. If the exit keys have not been defined they are set to the default exit keys. The following messages can be returned by TagItem: TI_OK - the requested action has been performed. TI_EXIT_KEY - a defined exit key has been pressed. Page -207- SCL1 Version 2.0 Reference Manual TagItem TI_MOUSE_EVENT - the mouse has been clicked but it has not been pointed to the area defined by the function. TI_ILLEGAL_KEY - an undefined key has been pressed. TI_MY_MOUSE - the mouse has been clicked after pointing to the area defined by the function. This message is in response to a TI_CHECK_MOUSE message. Example: #include <scl1.h> #include <scl1keys.h> #include <scl1clor.h> TIData ti={WHITE_BLACK,12,28,0,"Create Backup files",0,0}; main() { int Mess; Cls(WHITE_BLACK,0,0,24,79); TagItem(TI_RESET,&ti); TagItem(TI_DRAW,&ti); do { Mess=TagItem(TI_ACTIVE,&ti); }while(Mess != TI_EXIT_KEY); } Page -208- SCL1 Version 2.0 Reference Manual TagList Function: TagList Purpose: Displays in a ScrollBox any number of items that the user can tag using the keyboard (spacebar) or the mouse. Declaration: int TagList(int NColor, int RColor,struct TagList *tl); Returns: Return value is a number above "0" if the user pressed ENTER to exit, otherwise returns "-1". In case the user has pressed ESCAPE to exit the tagged items are returned in the same way as they were received. Parameters: The taglist information must be given as an array of structures as follows: struct TagList{ char TagFl; char *String; }; where, TagFl - equals "1" if item is tagged (char). String - a pointer to the item string (char). Note: The TagList structure must be zero terminated. The function is called with the following parameters: NColor - color used for box and items (integer). RColor - color used for selected item (integer). tl - pointer to structure TagList. This structure is defined in SCL1.H: Page -209- SCL1 Version 2.0 Reference Manual TagList Example: #include <scl1.h> #include <scl1clor.h> struct TagList tl[]={ 0,"Option 1", 0,"Option 2", 0,"Option 3", 0,"Option 4", 0,"Option 5", 0,"Option 6", 0,"Option 7", 0,"Option 8", 0,"Option 9", 0}; main() { int i; if(TagList(WHITE_BLACK,BLACK_WHITE,tl) != -1) /* cancel selected? */ { printf("\nThe following options were tagged:\n"); for(i=0;i < 9;++i) { if(tl[i].TagFl) printf("%s\n",tl[i].String); } } else printf("\nOperation canceled by user\n"); } NOTE: The new dialog type function TagList2 provides an alternative way to accomplish this task. Page -210- SCL1 Version 2.0 Reference Manual Taglist2 Function: TagList2 Purpose: Displays a list of items and permits tagging and untagging of selected items. The list will scroll vertically when the number of items is larger than the display length using the cursor keys or the mouse. Pressing the SPACEBAR key or clicking the mouse in a highlighted item tags the desired item. Declaration: int Taglist2(int Message,TLData *p,...) Returns: This is a dialog derived function. See Appendix "E" for a description of the general operation of these functions. The return value is a message described in the Messages section. Parameters: The Tag List information must be given in a structure defined as type TLData. The structure elements are as follows: typedef struct{ int NColor; int RColor; int TColor; int UpperRow; int LeftCol; int LowerRow; int RightCol; char **Array; char *TagArray; }TLData; where, NColor - color attribute for normal display (integer). RColor - color attributes for reversed display (integer). TColor - color attributes to be used for displaying a tagged item (integer). UpperRow - upper row coordinate of the window (integer). LeftCol - left column coordinate of the window (integer). Page -211- SCL1 Version 2.0 Reference Manual Taglist2 LowerRow - lower row coordinate of the window (integer). RightCol - right column coordinate of the window (integer). Array - pointer to array of pointers to be displayed. TagArray - a char pointer to an array that hold the tagging information about each item. The messages that can be sent to the TagList2 function are: TL_INIT - initialize the TLData structure as follows: NColor - set to white characters in a black background or the normal color defined by calling SetDialogColors. RColor - set to highlighted white characters in a black background or the normal color defined by calling SetDialogColors. TColor - set to black characters in a white background or the reversed color defined by calling SetDialogColors. UpperRow - set to row "6". LeftCol - set to column "5" for 40 column display and "34" for 80 column display. LowerRow - set to row "17" for 24 row display and "29" for 43 row display. RightCol - set to row "34" for 40 column display and "55" for 80 column display. TL_DRAW - display the Tag List with the current information. Page -212- SCL1 Version 2.0 Reference Manual Taglist2 TL_ACTIVE - browse through the displayed items and permit the selection or tagging of them using the cursor movement keys as follows: Key action Up Arrow cursor one item up. Down Arrow cursor one item down. END cursor to end of file list. HOME cursor to beginning of list. Page Up cursor one screen up. Page Down cursor one screen down. SpaceBar Tag or Untag an item The messages that TagList2 can return are: TL_OK - the requested action has been performed. TL_CANCEL - cancel the TagList2 operation. Example: #include <scl1.h> char *options[]={ "Option 1", "Option 2", "Option 3", "Option 4", "Option 5", "Option 6", "Option 7", 0}; char tarray[7]; main() { TLData tl; int i,Mess; Page -213- SCL1 Version 2.0 Reference Manual Taglist2 TagList2(TL_INIT,&tl); /* initialize structure */ tl.UpperRow=6; /* modify position */ tl.LowerRow=15; tl.LeftCol=20; tl.RightCol=60; tl.Array=options; /*initialize TagList2 to our data*/ tl.TagArray=tarray; TagList2(TL_DRAW,&tl); /* draw */ Mess=TagList2(TL_ACTIVE,&tl); /* active */ if(Mess==TL_OK) { printf("\nThe following options were tagged:\n"); for(i=0;i < 7;++i) { if(tarray[i]) printf("%s\n",options[i]); } } else printf("\nOperation canceled by user\n"); } Page -214- SCL1 Version 2.0 Reference Manual TagMenu Function: TagMenu Purpose: Displays a menu from which you can tag any or all of the available options. An item is toggled on or off by moving the highlighted bar with the arrow keys and then pressing the SPACEBAR or by clicking the mouse. The tagged options will be marked with a check mark. The menu items can be placed anywhere in the screen and in any desired order, you are not limited to placing all the menu options in successive lines. Upon exit you can either cancel the operation or continue. Declaration: int TagMenu(char NormalColor, char ReverseColor, char HighlightColor, char NumOpt,struct MenuOpt*, int XMin,int XMax,int YMin, int YMax); Returns: The returned value is "0" if the user selects the accept option and "-1" if the operation is cancelled. The calling program must check the first character of each selection of the structure to find out if a selection was tagged. Parameters: The menu information must be given as an array of structures as follows: struct MenuOpt{ int Row,Col; char *String; int Letter; }; where: Row - row position for the menu item (integer). Col - column position for the menu item (integer). String - pointer to the menu item text (char). Letter - letter to be highlighted for fast keyboard selection of the menu item (integer). Page -215- SCL1 Version 2.0 Reference Manual TagMenu Note: The last two options in the menu structure are the exit control codes to the function. First the option that cancels the operation and then the option that accepts the operation. The parameters passed to the function are: NColor - color attribute of the menu background and foreground (integer). RColor - color attribute of the highlighted item menu bar (integer). HColor - color attribute for the highlighted quick selection menu item letter (integer). NumOpt - number of menu options (integer). MenuOpt - pointer to the menu structure (char). XMin - minimum row position of menu area (integer). XMax - maximum row position of menu area (integer). YMin - minimum column position of menu area (integer). YMax - maximum column position of menu area (integer). Page -216- SCL1 Version 2.0 Reference Manual TagMenu Example: #include <scl1.h> #include <scl1clor.h> struct MenuOpt mo[]={ 9,35," Option 1 ",'1', 10,35," Option 2 ",'2', 11,35," Option 3 ",'3', 13,35," CANCEL ",'C', 14,35," OK ",'O', }; main() { int i; Cls(WHITE_BLACK,8,34,15,45); Box(WHITE_BLACK,1,8,34,15,45); if(TagMenu(WHITE_BLACK,BLACK_WHITE,WHITE_BLACK+HIGHLIGHT,5,mo, 35,44,8,15) != -1) { printf("The following options were tagged:\n"); for(i=0;i < 3;++i) { if(mo[i].String[0] != ' ') printf("Option %i\n",i+1); } } else printf("CANCEL was selected\n"); } Page -217- SCL1 Version 2.0 Reference Manual TextWindow Function: Textwindow Purpose: Displays text in a window. Declaration: int TextWindow(int Message,TWData *p,...); Returns: This is a dialog type function. See Appendix "E" for the general operation of these functions. The return value is a message described in the Messages section. Parameters: The options must be passed as an array of structures of the type TWData, one array element for each select option: Structure type TWData: typedef struct{ int Color; int UpperRow; int LeftCol; int LowerRow; int RightCol; int FrameType; int WrapFlag; int Position; }TWData; where, Color - color attributes for the window display (integer). UpperRow - upper row coordinate for the window's display (integer). LeftCol - left column coordinate for the window's display (integer). LowerRow - lower row coordinate for the window's display (integer). RightCol - right column coordinate for the window's display (integer). FrameType - any of the frame types available for the Box or GSSBox function (integer). Page -218- SCL1 Version 2.0 Reference Manual TextWindow WrapFlag - flag to indicate if the displayed line will be truncated or wrapped if the line's length exceeds the window's width. A value of "0" indicates no wrap and a value of "1" indicates wrap (integer). Position - structure element used internally to determine the current position within the window (integer). The following messages can be sent to TextWindow: TW_INIT - initialize the TWData structure to null and sets the following default values. Color - set to white characters in a black background or the normal color defined by calling SetDialogColors. LowerRow - set to row "24". RightCol - set to column "79". FrameType - set to single line frame. TW_DRAW - draw the text window to the screen. TW_WRITE - write the text information to the Text Window. TW_CLS - clear the window. TW_LINE_DOWN - move the cursor one line down. TW_DRAW_BORDER - draw border around the Text Window. TW_WAIT_ON - text will be written until the window is full then it stops and waits for a keypress. When a key is pressed the window is cleared. TW_WAIT_OFF - when the window is full it returns a TW_WINDOW_FULL message (default). TW_RESET - when this message is sent the position variables are reset to the default value. If the exit keys have not been defined they are set to the default exit keys. Page -219- SCL1 Version 2.0 Reference Manual TextWindow The following messages can be returned by TextWindow: TW_OK - the requested action has been performed successfully. TW_WINDOW_FULL - the Text Window is full. Example: #include <scl1.h> #include <scl1clor.h> char *strings[]={ "This strings will be written", "to a Text Window, one by one.", "Several control characters", "like\t\ttab (\\t),\nnew line (\\n)\rand carriage return (\\r)", "are supported."}; main() { TWData twd; int i,Mess; TextWindow(TW_INIT,&twd); /* initialize structure */ twd.UpperRow=10; /* modify position */ twd.LowerRow=14; twd.LeftCol=20; twd.RightCol=60; /* in this example we'll check for the WINDOW_FULL message and wait for a key to be pressed before writing anything else */ TextWindow(TW_DRAW,&twd); /* draw */ for(i=0;i < 5;++i) { Mess=TextWindow(TW_WRITE,&twd,strings[i]); if(Mess==TW_WINDOW_FULL) /* window full? */ { WriteScreen(WHITE_BLACK+HIGHLIGHT,13,21,"Press any key for more..."); GetKey(); } } Page -220- SCL1 Version 2.0 Reference Manual TextWindow /* now, we'll get the same effect using the WAIT_ON message, TextWindow will now stop and wait for a key when the window is full */ TextWindow(TW_DRAW,&twd); TextWindow(TW_WAIT_ON,&twd); for(i=0;i < 5;++i) TextWindow(TW_WRITE,&twd,strings[i]); } Page -221- SCL1 Version 2.0 Reference Manual TrapInt23 Function: TrapInt23 Purpose: Traps every occurrence of the Control+Break key combination. Global variable I23_CtrlBreakFl is incremented every time this keyboard combination is pressed. Declaration: void TrapInt23(void); Returns: Nothing Parameters: None Example: #include <scl1.h> main() { TrapInt23(); printf("Press Ctrl/Break to exit\n"); do { }while(I23_CtrlBreakFl==0); } Page -222- SCL1 Version 2.0 Reference Manual TrapInt24 Function: TrapInt24 Purpose: Critical error interrupt handler. Displays an error box showing the critical error that has occurred. Asks the user if he wants to retry or not the operation. This function is useful to avoid the familiar DOS message "Abort, Retry, Ignore?" from appearing on your screen. Also it gives you extra control when you are performing a series of file operations. If a file function returns "-1" it means that the user does not want to retry the operation, in this case the program can a stop the other I/O operations it was going to perform. This function only traps critical errors like: disk drive door opened, printer off-line, trying to read an unformatted disk, etc. To initialize TrapInt24 call it at the beginning of your program. It should be called ONLY ONCE. You can alter the error box appearance by calling the SetInt24Colors, Int24ShadowOff and Int24ShadowOn functions. The function saves and restore the screen area where the error box is displayed. To initialize TrapInt24 call it at the beginning of your program. Declaration: void TrapInt24(void); Returns: Nothing Parameters: None Example: #include <scl1.h> main() { TrapInt24(); . . } See also SetInt24Colors, Int24ShadowOff and Int24ShadowOn. Page -223- SCL1 Version 2.0 Reference Manual TSound Function: TSound Purpose: Plays a sound of the specified frequency and for a specified length of time (in hundredths of a second). Declaration: void TSound(int Frequency, unsigned int Duration); Returns: Nothing Parameters: Frequency - the note frequency in Hertz (integer). Duration - length of the note in hundredths of a second (unsigned integer). Example: #include <scl1.h> main() { TSound(1000,100); /* Plays a 1000 Hertz tone for one second */ } See the note definitions in header file SCL1SND.H. Page -224- SCL1 Version 2.0 Reference Manual Video Function: Video Purpose: Checks the monitor type. Detects if the video adapter in use is either Monochrome or Color. Declares and defines the variable VideoSeg (unsigned int) that holds Video Buffer segment address. (The VideoConfig function provides additional information) Declaration: unsigned int Video(void); Returns: The return value is defined in SCL1.H as MONO if a monochrome monitor is installed, or COLOR if a color monitor is installed. Parameters: None Example: #include <scl1.h> main() { if(Video()==MONO) printf("You have a monochrome monitor\n"); else printf("You have a color monitor\n"); } See also VideoConfig. Page -225- SCL1 Version 2.0 Reference Manual VideoConfig Function: VideoConfig Purpose: Checks the video information of your system. Fills a structure with the current video information for use by other functions. This function will be called by the first function that uses direct video write. Also sets global variables VC_Monitor, VC_Mode, VC_Page, VC_Lines, VC_Cols, VC_Retrace and VC_Segment with the current video information. Declaration: struct VideoData *VideoConfig(void); Returns: The return value is a pointer to the VideoData structure. Parameters: The video information is stored in a structure type VideoData: struct VideoData{ int Monitor; int Mode; int Page; int Lines; int Cols; unsigned int Segment; int Retrace; }; where, monitor - type of monitor detected. The following types have been defined in SCL1.H (integer): VC_MDA = Monochrome VC_CGA = CGA monitor VC_EGA = EGA monitor VC_EGAM = EGA with monochrome monitor VC_PGC = Professional graphic VC_VGAM = VGA / monochrome VC_VGA = VGA VC_MCGADC = MCGA Digital VC_MCGAAM = MCGA Analog/mono VC_MCGAAC = MCGA Analog/color Mode - active video mode (integer). Page - active video page (integer). Page -226- SCL1 Version 2.0 Reference Manual VideoConfig Lines - number of rows in current video mode (integer). Cols - number of columns in current video mode (integer). Segment - segment used by current video mode (unsigned integer). Retrace - structure element that tells the functions to use or not to use retrace. If value is to "0" the direct screen writes will use no retrace if value is "1" the will use retrace. By default this value will be set to "0" with all video systems except VC_CGA. Example: #include <scl1.h> char *vs[]={ "", "Monochrome", "CGA", "", "EGA", "EGA - mono", "PGC", "VGA - mono", "VGA", "", "MCGA - digital - color", "MCGA - analog - mono", "MCGA - analog - color", }; main() { struct VideoData *vd; vd=VideoConfig(); printf("\n Video system: %s\n",vs[vd->Monitor]); printf(" Video mode: %i\n",vd->Mode); printf(" Active page: %i\n",vd->Page); printf(" Lines: %i\n",vd->Lines); printf(" Columns: %i\n",vd->Cols); printf("Buffer segment: %X\n\n",vd->Segment); } See also Video. Page -227- SCL1 Version 2.0 Reference Manual WaitKeyMouse WaitTime Function: WaitKeyMouse Purpose: Waits for a keystroke or pressing of the left mouse button. The function clears the keyboard buffer on entry. Declaration: unsigned int WaitKeyMouse(void); Returns: Returns the key's Scan/Ascii code if a key pressed. Parameters: None Example: WaitKeyMouse(); **************************************************************** Function: WaitTime Purpose: Sets a delay of X hundredths of a second. Declaration: void WaitTime(unsigned int HSec); Returns: Nothing Parameters: HSec - time interval in hundredths of a second. Example: WaitTime(200); /* Sets a 2 second delay */ Page -228- SCL1 Version 2.0 Reference Manual WFilebox Function: WFileBox Purpose: Displays a wide box with the directory information for loading or selecting files. Fills a buffer with the selected file/path. The function accepts mouse input. Declaration: int WFileBox(int Message, FBData *p) Returns: This is a dialog derived function. See Appendix "E" for a description of the general operation of these functions. The return value is a message described in the Messages section. Parameters: The file box information is given in a structure type FBData as follows: Structure type FBData; typedef struct{ int NColor; int RColor; int UpperRow; int LeftCol; int LowerRow; int RightCol; char *Filename; int Attrib; }FBData; where, NColor - normal color for the file box's display (integer). RColor - reversed color for the file box's display (integer). UpperRow - upper row coordinate for the file box's display (integer). Page -229- SCL1 Version 2.0 Reference Manual WFilebox LeftCol - left column coordinate for the file box's display (integer). LowerRow - lower row coordinate for the file box's display (integer). RightCol - right column coordinate for the file box's display (integer). Filename - pointer to buffer to hold selected filename. The search string is placed in the buffer before calling the function. If an empty buffer is used (NO SEARCH STRING SPECIFIED), the function will place the default path and the "*.*" search string in the buffer. Attrib - file attributes as defined by the DOS. Please refer to Appendix "A", FILE FUNCTIONS, for more details (integer). Messages: The following messages can be sent to WFilebox: FB_INIT - initialize the FBData structure to NULL and set the following default values: NColor - set to white characters in a black background or the normal color defined by calling SetDialogColors. RColor - set to black characters in a white background or the reversed color defined by calling SetDialogColors. LeftCol - set to column "20" for 80 column displays or to column "0" for 40 column displays. LowerRow - set to row "24" for 25 row displays or to row "42" for 43 row displays. RightCol - set to column "39" for 40 column display and "79" for 80 column displays. Page -230- SCL1 Version 2.0 Reference Manual WFilebox Attrib - files and sub-directories. FB_DRAW - draw the Filebox to the screen. FB_ACTIVE - browse through the displayed filenames and permit selection or cancellling of the operation using the following keys: Key action Up Arrow cursor one item up. Down Arrow cursor one item down. Left Arrow cursor one item to the left. Right Arrow cursor one item to the right. END cursor to end of file list. HOME cursor to beginning of list. The following messages can be returned by WFileBox: FB_OK - the action requested has been performed and no selection has been made. FB_CANCEL - the operation has been cancelled. Example: #include <scl1.h> #include <scl1clor.h> char Buffer[80]; int Color1=WHITE_BLACK; int Color2=BLACK_WHITE; main() { FBData fbd; WFileBox(FB_INIT,&fbd); /* initialize the FBData structure */ fbd.NColor=Color1; /* change display colors */ fbd.RColor=Color2; fbd.Filename=Buffer; /* set buffer to hold directory info */ fbd.Attrib=F_READ_ONLY+F_HIDDEN+F_SYSTEM+F_DIRECTORY; /* set files attributes */ WFileBox(FB_DRAW,&fbd); /* display FileBox */ WFileBox(FB_ACTIVE,&fbd); /* let user make a selection */ } Page -231- SCL1 Version 2.0 Reference Manual Window Function: Window Purpose: Saves, clears and restores a window. Declaration: void Window(int Color,int UpperRow,int LeftCol, int LowerRow, int RightCol, char* Flag, char* Buffer); Returns: Nothing Parameters: Color - color attribute for the area to be cleared (integer). UpperRow - upper left row coordinate of the area (integer). LeftCol - upper left column coordinate of the area (integer). LowerRow - lower right row coordinate of the area (integer). RightCol - lower right column coordinate of the area (integer). Flag - pointer to a variable that holds the action to be performed: 0 -> save and clear area. -2 -> save area only. 1 -> restore area (saved and cleared). -1 -> restore area (saved only). Buffer - pointer to a buffer to hold the screen information. Page -232- SCL1 Version 2.0 Reference Manual Window Notes: 1. The flag is toggled automatically every time the function is called. 2. The buffer size is the Number of characters * 2 Example: #include <scl1.h> #include <scl1keys.h> #include <scl1clor.h> /* screen data is stored in these buffers, use W_BUF_SIZE macro to calculate buffer size */ char buffer1[W_BUF_SIZE(0,0,24,79)]; char buffer2[W_BUF_SIZE(9,26,15,52)]; main() { char WFlag1=-2; /* save do not clear screen */ char WFlag2=0; /* save and clear screen */ Window(BLACK_WHITE,0,0,24,79,&WFlag1,buffer1); FillBlock(WHITE_BLACK,0,0,24,79,'X'); WriteScreenLen(BLACK_WHITE,24,0,70," The whole screen has been saved, press any key..."); GetKey(); Window(WHITE_BLACK,9,26,15,52,&WFlag2,buffer2); WriteScreenLen(BLACK_WHITE,24,0,70," A second window was SAVED AND CLEARED, press any key to restore it..."); GetKey(); Window(WHITE_BLACK,9,26,15,52,&WFlag2,buffer2); WriteScreenLen(BLACK_WHITE,24,0,70," Press any key to restore the screen..."); GetKey(); Window(BLACK_WHITE,0,0,24,79,&WFlag1,buffer1); } Page -233- SCL1 Version 2.0 Reference Manual WriteChar Function: WriteChar Purpose: Writes a character directly to the screen buffer a specified number of times. Declaration: void WriteChar(int Color, int Row, int Col, int Count, int Character); Returns: Nothing Parameters: Color - color attribute for the character to be displayed (integer). Row - row coordinate of position to start display (integer). Col - column coordinate of position to start display (integer). Count - number of times the character is written (integer). Character - the character to be displayed (integer). Example: #include <scl1.h> #include <scl1clor.h> int Color1=WHITE_BLACK; main() { WriteChar(Color1,10,0,80,'-'); } /* Writes 80 dashes to the screen starting in line 10, column 0*/ Page -234- SCL1 Version 2.0 Reference Manual WriteFile Function: WriteFile Purpose: Writes to a file. The function can also be used to write to the standard printer, console or any other standard device if the proper handle number is specified. Declaration: int WriteFile(int Handle,char *Buffer, unsigned int Bytes); Returns: The return value is "0" if no error occurs or the DOS error code if an error occurs. (See Appendix "A", FILE FUNCTIONS, for more information). Parameters: Handle - handle number given by DOS when you open or create a file (integer). Buffer - pointer to the buffer that will hold the data. Bytes - number of bytes to write (unsigned integer). Example: #include <scl1.h> /* This is the source code of the Buf2Disk function */ Buf2Disk(char *Filename,char *Buffer,unsigned int Bytes) { int i,handle; if(i=CreateFile(Filename,&handle,F_ARCHIVE)) return(i); if(i=WriteFile(handle,Buffer,Bytes)) { if(i > 0) CloseFile(handle); return(i); } return(CloseFile(handle)); } Page -235- SCL1 Version 2.0 Reference Manual WriteOffLen Function: WriteOffLen Purpose: Writes a string directly to the video buffer. The length to display is specified. If the string is shorter than the specified length, the remaining spaces are filled with the space character. The display position is specified as an offset from the home position. Declaration: void WriteOffLen(int Color, int Offset, int Count, char * String); Returns: Nothing Parameters: Color - color attribute of the desired display (integer). Offset - offset from the home position where to display the string. The offset is calculated as follows: number of columns multiplied by "2" multiplied by the number of rows plus the desired column position multiplied by "2" (integer). Count - length to display (integer). String - pointer to the string to be displayed. Example: #include <scl1.h> #include <scl1clor.h> int Color1=WHITE_BLACK; main() { WriteOffLen(Color1,1500,15,"This is a test. "); } /* Displays the string with a length of 15 character in position offset 1500 */ Page -236- SCL1 Version 2.0 Reference Manual WriteOffset Function: WriteOffset Purpose: Writes a character directly to the video buffer. The display position is specified as an offset from the home position. Declaration: void WriteOffset(int Color, int Offset, int Character); Returns: Nothing Parameters: Color - color attribute of the desired display (integer). Offset - offset from the home position where to display the string. The offset is calculated as follows: number of columns multiplied by "2" multiplied by the number of rows plus the desired column position multiplied by "2" (integer). Character - character to be displayed (integer). Example: #include <scl1.h> #include <scl1clor.h> #define ROW 10 #define COL 60 char string[]="IN GIRUM IMUS NOCTE ET CONSUMIMUR IGNI"; main() { int offset,i; InitVideo(); WriteScreen(BLACK_WHITE,ROW-1,23,string); offset = ROW * VC_Cols * 2 + COL * 2; for(i=0;i < sizeof(string)-1;++i,offset-=2) WriteOffset(BLACK_WHITE,offset,string[i]); } Page -237- SCL1 Version 2.0 Reference Manual WriteScreen Function: WriteScreen Purpose: Writes a string directly to the video buffer. Supports control character "\n". Declaration: void WriteScreen(int Attribute, int Row, int Column, char* StringAdr); Returns: Nothing Parameters: Attribute - color attribute of the desired display (integer). Row - row coordinate where to display the string (integer). Column - column coordinate where to display the string (integer). StringAdr - pointer to the string to be displayed. Example: #include <scl1.h> #include <scl1clor.h> char Mess[]="SCL1's screen related functions will let you:\n\n" " ∙ Write directly to the screen.\n\n" " ∙ Draw boxes.\n\n" " ∙ Clear or scroll any area of your screen.\n\n" " ∙ Save and restore any screen area.\n\n" " ∙ Control cursor size and many more..."; int Color1=WHITE_BLACK; main() { WriteScreen(Color1,4,20,Mess3); } /* Displays the string Mess3[] in row 4, column 20 */ Page -238- SCL1 Version 2.0 Reference Manual WriteScreenLen Function: WriteScreenLen Purpose: Writes a string directly to the video buffer. The length to display is specified. If the string is shorter than the specified length, the remaining spaces are filled with the space character. Declaration: void WriteScreenLen(int Color, int Row, int Col, int Count,char *String); Returns: Nothing Parameters: Color - color attribute of the desired display (integer). Row - row coordinate where to display the string (integer). Col - column coordinate where to display the string (integer). Count - length to display (integer). String - pointer to the string to be displayed. Example: #include <scl1.h> #include <scl1clor.h> char string1[]="Only the characters that fit inside the box will written to the screen."; char string2[]="WriteScreenLen blanks the screen if the string\nis shorter than the length specified:"; char *strings[]={"1234567890", "12345678", "12345"}; Page -239- SCL1 Version 2.0 Reference Manual WriteScreenLen main() { int TopRow,LeftCol,BottomRow,wide,i; for(TopRow=LeftCol=4,BottomRow=TopRow+2,wide=72;wide > 4; wide-=2,++LeftCol) { Box(BLACK_WHITE,0,TopRow,LeftCol,BottomRow,LeftCol+wide); WriteScreenLen(BLACK_WHITE,TopRow+1,LeftCol+1,wide-1,string1); GetKey(); } Cls(BLACK_WHITE,10,10,14,70); WriteScreen(BLACK_WHITE,11,17,string2); for(i=0;i < 3;++i) { WriteScreenLen(BLACK_WHITE,13,35,34,strings[i]); GetKey(); } } Page -240- SCL1 Version 2.0 Reference Manual YesNo Function: YesNo Purpose: Displays a YES/NO query box with mouse control buttons. The original screen is restored on exit. Declaration: int YesNo(int NColor,int RColor,int Selection, char *p); Returns: A value of "1" is returned if the YES box is selected or clicked with the mouse and a value of "2" if the NO box is selected or clicked. Parameters: NColor - color attribute for the YES/NO box (integer). RColor - color attribute of the selected option (integer). Selection - default selection (integer). p - pointer to the question whose answer is seeked. Example: #include <scl1.h> #include <scl1clor.h> #define YES 1 #define NO 2 int Color1=WHITE_BLACK; int Color2=BLACK_WHITE; main() { do { if(YesNo(Color1,Color2,"Turn YesNo Box\nShadow On?") == YES) YesNoShadowOn(); if(YesNo(Color1,Color2,"Turn YesNo Box\nShadow Off?") == YES) YesNoShadowOff(); }while(YesNo(Color1,Color2,NO,"Exit to DOS?") != YES); } See YesNoShadowOff and YesNoShadowOn Page -241- SCL1 Version 2.0 Reference Manual YesNoShadowOff YesNoShadowOn Function: YesNoShadowOff YesNoShadowOn Purpose: Displays or disable a shadow effect when using the YesNo function. After any of these functions are called all subsequent calls to the YesNo function will be displayed with (or without) a shadow effect. Declaration: void YesNoShadowOff(void); void YesNoShadowOn(void); Returns: Nothing. Parameters: None. Example: #include <scl1.h> #include <scl1clor.h> #define YES 1 #define NO 2 int Color1=WHITE_BLACK; int Color2=BLACK_WHITE; main() { do { if(YesNo(Color1,Color2,"Turn YesNo Box\nShadow On?") == YES) YesNoShadowOn(); if(YesNo(Color1,Color2,"Turn YesNo Box\nShadow Off?") == YES) YesNoShadowOff(); }while(YesNo(Color1,Color2,NO,"Exit to DOS?") != YES); } See YesNo. Page -242- Appendix "A" FILE RELATED FUNCTIONS SCL1's file related functions rely on DOS services to work with files. They provide an alternative to the standard library functions with a main objective of providing an easier way to trap and display error related information. You can classify errors in two groups; critical and non- critical. Critical errors are those that generate an interrupt 0x24 like, for example, a disk drive door left opened. This is the type of error that generates the DOS message "Retry, Abort, Ignore?". Non-critical errors are reported by the system but do not generate an interrupt 0x24 like, for example, not finding a file. SCL1 functions deals with non-critical errors in a simple way. Most file functions return zero if the operation was successful, otherwise they return the DOS error code that identifies the type of error. Your program can then process the error code or you can call the ErrorBox function that will display the error message. You can add your own errors to ErrorBox default error messages (see ErrorBox). To deal with DOS critical errors, SCL1 has the TrapInt24 function. Call this function at the beginning of your program (it must be done only once) and any subsequent critical errors will be handled by SCL1. Now if DOS generates an interrupt 0x24, instead of its standard message, a window will be opened in the screen's center and a message indicating the type of error, disk or printer related, and asking the user if he wants or not to retry operation will be displayed. On exit the original screen will be restored. Once you have initialized TrapInt24, SCL1's file related functions will return -1 to indicate a DOS critical error if the user decided NOT TO retry the operation. If the user decides to retry the operation and it is completed successfully, no error code is reported. As you see, trapping critical errors and non-critical errors can be easily integrated to your program by using TrapInt24 and ErrorBox. SCL1's way of displaying error message is specially appropriate for programs that are not command-line oriented. Also notice that you don't have to use ErrorBox when a critical error is reported since TrapInt24 has its own way of displaying error messages. Refer to the DOS Technical Reference for more information about error code numbers. Page -243- Appendix "A" The following pseudo-code shows how to deal with errors: Returned error code > than 0 ? Call ErrorBox with error number. Error code = -1 ? DOS Critical error, the user choose not to retry operation. No need to call ErrorBox since the error message has already been displayed by TrapInt24. else Operation was successful. The following list show the most common DOS error codes: 2 File not found 3 Path not found 4 No handles left 5 Access denied 6 Invalid handle 15 Invalid drive 16 Attempt to remove current directory 29 Write Fault 30 Read Fault SCL1's Error codes: 255 File too big (used by File2Buf) -1 Dos Critical error -2 Drive not valid (used by GetDiskFreeSpace) SCL1 gives you direct access to DOS file related functions. You need to understand DOS's way of working with files for using them. There are many books that could help you. The general procedure is: First you must open or create a file. Use OpenFile or CreateFile to do it. The first function opens an existing file (error is reported if the file is not found ), while the second one creates a file if the file is not found or truncates an existing file to 0. When you open or create a file DOS gives you a "Handle". A handle is a number that you will use to refer to this file when performing any other operations like reading, writing, etc. Page -244- Appendix "A" Once you have a handle to a file you can write or read data. To do it use ReadFile or WriteFile. This functions will read or write any number of bytes to or from a buffer you specify. Files functions under DOS have a read/write pointer. In other words, when you read 200 bytes the file pointer will point to byte 201. This means that next time you read, you will read byte 201. This pointer is automatically moved by ReadFile and WriteFile. You can move this pointer yourself using MoveFilePt and MoveFilePt2Offset. Once you have finished working with your file, you must close the file by using CloseFile. As you see working with files under DOS is a three step process: 1) Open/Create File, 2) Read/Write, 3) Close File. SCL1 offers another, and probably easier, way to work with files. You can read a file to a buffer or write a buffer to a file in just one step using File2Buf and Buf2Disk. You don't have to care about opening or closing files with this functions. But you will have to read or write the whole file/buffer when you use them. Page -245- Appendix "B" MOUSE RELATED FUNCTIONS All SCL1 mouse related functions are based on an interrupt service routine (ISR) that updates a series of variables according to the mouse current state. If you do not initialize this ISR you would not be able to use any mouse related routine. Mouse initialization can be performed in several ways. The CheckMouse function can be used to check if the mouse hardware/software is installed: if(CheckMouse()) we have a mouse ! Once you have verified that the mouse is installed you should reset the mouse software to its defaults using ResetMouse and then proceed to install the ISR using SetMouseIsr: if(CheckMouse()) { ResetMouse(); SetMouseIsr(); Now you can call any mouse related functions. You can begin by calling ShowMouse to make the mouse visible. NOTE: Before returning to DOS should program must un-install the ISR using ResetMouse(). Failure to do so might cause unpredictable problems. All these steps can be simplified by using InitMouse function. This function performs all the operations described above including resetting the ISR: If you want a visible mouse cursor use: InitMouse(IM_SHOW); If you want an invisible mouse cursor use: InitMouse(IM_NO_SHOW); Once the mouse is initialized a series of variables are updated according to mouse events (see SetMouseIsr). Your program can check these variables at any moment to read the mouse position and the mouse buttons state. Page -246- Appendix "B" NOTE: If you change video modes you should reset the mouse and re-initialize it. The re-initialization MUST NOT be done using InitMouse: InitMouse(IM_SHOW); . . ResetMouse(); SetVideoMode(1); if(CheckMouse()) { ResetMouse(); SetMouseIsr(); ShowMouse(); } Page -247- Appendix "C" SCREEN RELATED FUNCTIONS All SCL1's screen related functions write directly to the video buffer. Configuration according to monitor type is done automatically when the first screen related function is called. During this configuration, SCL1's Video function will determine the type of monitor, the video buffer memory address and wether it is necessary to wait for the monitor retrace to avoid snow. To learn about the video configuration your program will be using you should call VideoConfig. This function returns a pointer to a structure that holds the information about the video adapter you'll be using. The structure format is as follows: struct VideoData{ int Monitor; /* Monitor type */ int Mode; /* Active video mode */ int Page; /* Active video page */ int Lines; /* Number of lines in video mode */ int Cols; /* Number of columns in video mode */ unsigned int Segment; /* video buffer segment address */ int Retrace; /* =1 if retrace is to be done */ }; Monitor types are define in SCL1.H : VC_MDA = Monochrome VC_CGA = CGA monitor VC_EGA = EGA monitor VC_EGAM = EGA with monochrome monitor VC_PGC = Professional graphic VC_VGAM = VGA / monochrome VC_VGA = VGA VC_MCGADC = MCGA Digital VC_MCGAAM = MCGA Analog/mono VC_MCGAAC = MCGA Analog/color If you do not need all the video information you can call Video. This functions returns wether the monitor is color or mono: if(Video()==COLOR) color monitor else mono monitor NOTE: COLOR & MONO are defined in SCL1.H as the segment address of the Video Buffer (0xb800 for color 0xb000 for mono). Page -248- Appendix "C" SCL1 video functions work only in alphanumeric video modes. You can initialize your system to one of this modes (3 in case of color, 7 in case of mono) by calling InitVideo at the beginning of your program. Most of the times this won't be necessary since they are the default modes, but is not a bad idea to use InitVideo just to make sure. Be aware that when you call InitVideo the screen will be cleared and the cursor moved to the screen's home position. Remember that version 2.0 of SCL1 supports only video modes 0 - 3 and 7. SCL1's screen related functions always write to the active video page. You can change the video page using SetVideoPage. Be sure to specify a valid page for your system. You can force a function to write to a non-active video page by modifying the VC_Page variable before calling the desired video function, be sure to restore the correct value of VC_Page. Retrace will be done only if a CGA type adapter is found. SCL1 functions will not wait for the video retrace if an EGA adapter is found. Yet you can force them to do the retrace by changing the variable VC_Retrace to 1. For example: if(Video()==COLOR) VC_Retrace=1; You must set this variable to 1 AFTER having called Video or any other screen related function. EGA 43 lines and VGA 50 lines are now supported by SCL1. SetVideo4350 sets the mode to 43 or 50 lines depending on the monitor you have. SetVideo25 restores video mode to the default 25 lines. Page -249- Appendix "D" SCL1 HEADER FILES SCL1.H - SCL1 structures, functions prototypes and constant definitions. SCL1KEYS.H - SCAN-ASCII code of most used keys. F1 - F10 (with shift, alt and control), numeric key-pad keys and A- Z (with alt and control) are defined. SCL1CLOR.H - Color definitions. Example: WHITE_BLUE stands for white characters on blue background. Colors can be highligted and the blink attribute is also defined. Example: WHITE_RED | HIGHLIGHT WHITE_RED | BLINK SCL1SND.H - Definition of musical notes frequency in hertz to be used with sound related functions. Syntax TS_X[y]? , were: TS = TSound id X = musical note (C,D,E,F,G,A,B) y = s means sharp, f means flat (optional) ? = octave (1 - 7) Examples: TS_Df4 = D flat, fourth octave TS_C4 = C, fourth octave (middle C) SCL1OLD.H - Use this file only to compile source-code developed with SCL1 version 1. Several global variables names and constant definitions has changed in version 2. SCL1OLD.H redefines older names to the new names used in SCL1 version 2. Page -250- Appendix "E" DIALOG TYPE FUNCTIONS OVERVIEW In this version of SCL1 several new functions have been added that utilize a dialog scheme. The idea behind these functions is to make them as flexible as possible, permitting the programmer to set or specify almost any available parameter. This flexibility adds complexity and, in order to make them as friendly as possible, a dialog scheme has been used. During program development a need arises to perform complex task. For example; let's say you need to get user input, but you want to add the flexibility of being able to check for a help key or for a keystroke combination that will insert a block at the current cursor position. Or you need a window were the user can browse through a list of items, yet you want to know exactly at any moment what item is being highlighted by the user so that you can display help information or show the selected item in another window. These types of requirements usually require you to write a custom procedure. Most library functions are not designed to handle these special requirements. The dialog type functions have been designed to permit you to handle these types of problems. To permit this level of flexibility, the dialog type functions make use of a message interchange scheme. You can call the function as many times as required, each time requesting a given action. The function will return a message that gives you the results or status of the requested action. The general way to use this functions is as follows: You can first call the function with an initialization message. This will take care of initializing the structure elements to some predetermined values and setting the function's initial conditions. Then you can call the function with a message requesting a display. This will instruct the function to draw or display to the screen the desired object (like a scroll window display). Now that there is a display you will like to make the function active so that it can perform the desired task. While the function is active it will keep sending back messages informing you of what is happening, for example, that an illegal key has been pressed (so display an error or help message, or beep the console to warn the user, etc.) or that the cursor has changed position, etc. You can then analyze these returned messages and respond with a given action or you can ignore them. In fact, you can request the function to do anything it is capable of doing, for example, in the case of data entry field (like LineEditor), to move the cursor to any position, reformat Page -251- Appendix "E" or even change the data, insert a new character, etc. The messages have been defined in the header file as english-like messages to permit a friendly interface. Most of the parameters needed to configure the functions are included as elements of one or several structures. These structure(s) need to be initialized before any call to the function is made. The structures contain a lot of parameters and it might look as if they involve a lot of effort to define them. With the aid of SSG (SCL1 Screen Generator program) you can define these structures very easily. Please refer to the SSG reference manual included in this package. SENDING MESSAGES TO DIALOG TYPE FUNCTIONS Every effort has been made to make the dialog functions as uniform as possible. Most functions use the same messages to perform the same tasks. INITIALIZING THE PARAMETER STRUCTURES: You can define the parameter structures in two different ways. One way is to indicate a value for each parameter. The other way is to call the functions with a "INIT" message, this will assign default values to most parameters, then you can modify them according to your taste. Which method to use depends on how many of the parameters you will like to have control of. For example, let us initialize a ScrollWindow structure using the two methods: 1) Using SW_INIT message: #include <scl1.h> /* This is the data you want to display in your scroll window */ char *swdbuf[]={ "First Item", "Second Item", 0}; main() { SWData swd; Page -252- Appendix "E" /* This initializes the structures to certain default values (see each function description for details). Once it has been initialized you need to modify only the desired parameters */ ScrollWindow(SW_INIT,&swd); /* Modify the size of our scroll window */ swd.UpperRow=6; swd.LeftCol=26; swd.LowerRow=17; swd.RightCol=52; /* And specify our data address */ swd.Buffer=swdbuf; 2) Defining the structure as static data: #include <scl1.h> /* This is the data you want to display in your scroll window */ char *swdbuf[]={ "First Item", "Second Item", 0}; /* All the parameters required to define the Scroll Window go into this structure (size, color, position, etc.). */ SWData swd={7,15,6,26,17,52,0,1,15,swdbuf,0,0," Scroll Window",7,0,0,0,0,0,0,0,0,0,0,0,0,0}; /* Since all the parameters have been defined there is no need to change any of them */ THE "RESET" MESSAGE: Dialog function structures have several position related variables. When you declare your structure as static data you do not need to call the function with an "INIT" message. You should call the function with a "RESET" message to make sure that all these variables are reset. This message also checks for undefined ExitKeys an sets this element to default values if the have not been defined. Page -253- Appendix "E" Let us continue with the previous example of an application of the ScrollWindow function. Let us assume that the structure has been defined as static data. Our program should look like this: main() { /* The RESET message resets the internal position related variables (in this case, it makes sure that we start at the first item. It also checks for any parameter that may have not been specified in the structure (in this example the ExitKeys have not been specified). You should always call a dialog function using the "RESET" message when you are not using the "INIT" message unless you desire the cursor to appear over an specific item */ ScrollWindow(SW_RESET,&swd); } THE "DRAW" MESSAGE: Once your structure is defined and initialized there a lot messages that you can send to it. The first message usually is "DRAW", this message instructs the function to display the information to the screen. In our example using the ScrollWindow function the "DRAW" message should be sent like this: ScrollWindow(SW_DRAW,&swd); After sending this message you should see a the Scroll Window displayed in the screen. THE "ACTIVE" MESSAGE: The "ACTIVE" message permits you to have the function perform the specific task it has been designed to do. Messages are constantly returned by the dialog type function. If you are using the LineEditor function, the "ACTIVE" message permits you to edit the entry field, for the ScrollWindow function, this message lets you browse through the window, etc. Page -254- Appendix "E" When you send this message the function will retain the program control until some event occurs. For example, in the case of ScrollWindow, when the user press the DOWN or UP arrow keys to change the highlighted item, ScrollWindow will return a NEW_POSITION message, or if you pressed an undefined key (it could be F1 to request Help) an ILLEGAL_KEY message is returned. You can ignore the returned message or respond to it. In our previous example of a the ScrollWindow function the code should look like this: do { Mess=ScrollWindow(SW_BROWSE,&swd); }while(Mess != SW_EXIT_KEY); Since when an "ACTIVE" message is sent the function retains the program control until an event occurs, we should place this function call within in a loop. In this case any returned message is ignored except the "EXIT_KEY" message which means that a key defined as an exit key has been pressed. The user will be able to browse until one of these keys is pressed. Exit Keys can individually be defined for each function. You can add any desired Exit Keys by defining a null-terminated array were all the ExitKeys' SCAN/ASCII codes values are specified, for example: unsigned int MyExitKeys[]={ESC,ENTER,0}; NOTE: This example needs header file SCL1KEYS.H. Once you have defined your Exits Keys you initialize the structure ExitKeys element: swd.ExitKeys=MyExitKeys; You can also call the function with the "INIT" and "RESET" messages to set the ExitKeys to default values (see each function description) THE "POSITION_BEGIN" MESSAGE When you call the function with this message the cursor moves to the start of the data buffer. Page -255- Appendix "E" The "POSITION_END" MESSAGE When you call the function with this message the cursor moves to the end of the data buffer. The "POSITION_UP" MESSAGE When you call the function with this message the cursor moves one position towards the end of the data buffer in the LineEditor function, to the next field for the Fields2 function and to the next item in all other functions. The "POSITION_DOWN" MESSAGE When you call the function with this message the cursor moves one position towards the start of the data buffer in the LineEditor function, to the next field for the Fields2 function and to the next item in all other functions. The "SET_POSITION" MESSAGE When you call the function with this message the cursor moves to the specified position. This function call requires you to send an additional parameter (see explanation below). The "CHECK_MOUSE" MESSAGE Normally Dialog type functions handle the mouse input by themselves but when you have several Dialog type functions at the same time on the screen and your program detects that the mouse has been clicked you can send this message to any dialog function. If the mouse was clicked inside a function screen area it will return a MY_MOUSE message, in any other case it returns a MOUSE_EVENT message. This call is useful for determining under what conditions the mouse has been clicked. MESSAGES THAT DIALOG TYPE FUNCTIONS CAN RETURN THE "OK" MESSAGE. This message is returned when you have called a Dialog type function with the "DRAW", "INIT" or "RESET" messages, and the action was performed as requested. Page -256- Appendix "E" THE "EXIT_KEY" MESSAGE. This message is returned when one of the keys, defined as an Exit Key, has been pressed. It's SCAN/ASCII code is stored in the structure element "EventInfo". THE "ILLEGAL_KEY" MESSAGE: Each function uses several keys (like PgUp, PgDn etc.) to perform common operations and checks for the use of the defined ExitKeys. If any other key is pressed, it returns an ILLEGAL_KEY message and stores the key's SCAN/ASCII code in the structure's EventInfo element. You can respond to this message for performing a given action. Let us see an example in which we use the ILLEGAL_KEY message to display a help screen and at the same time display the highlighted item in a secondary window: do { Mess=ScrollWindow(SW_ACTIVE,&swd); if(Mess==SW_ILLEGAL_KEY) /* Illegal key pressed? */ { /* The structure's EventInfo element is common to all Dialog function. It holds the value of the key that was pressed when you receive and EXIT_KEY or ILLEGAL KEY message. */ if(swd.EventInfo == F1) /* Help Key? */ ... Display help code would go here .... else /* Unknown key */ ... Display error message, beep etc. } /* Let's now display the highlighted item in a secondary window, the structure Position element can be used as an index to our data array */ WriteScreen(7,24,30,swdbuf[swd.Position]); }while(Mess != SW_EXIT_KEY); Page -257- Appendix "E" You can send other messages while you're inside this loop. For example, in this loop the item at the cursor position is deleted from the list when the DELETE key is pressed: do { Mess=ScrollWindow(SW_BROWSE,&swd); if(Mess == SW_ILLEGAL_KEY && swd.EventInfo == DEL) { /* DeleteItem would be an user defined function that deletes an item from your list */ DeleteItem(swd.Position); /* Now redraw your data */ Mess=ScrollWindow(SW_DRAW,&swd); }while(Mess != SW_EXIT_KEY); THE "MOUSE EVENT" MESSAGE This message is returned when the mouse has been clicked outside the function screen area. You can check mouse variables MSE_LpX and MSE_LpY to get the actual position were the mouse was clicked. THE "MY_MOUSE" MESSAGE When you send a "CHECK_MOUSE" message to a dialog function it checks if the mouse was clicked inside it's screen area. In this case it will return a "MY_MOUSE" message. You can then send an "ACTIVE" messages so that the function gets control and services the mouse event. In the case the mouse was clicked outside it's screen area a "MOUSE_EVENT" message is returned. THE "BUFFER_END" MESSAGE This message is returned when the user has tried to move the cursor passed the last element (or end) of the buffer. This message can be safely ignored unless you want to display an error or warning. (This message is not supported by all Dialog functions). Page -258- Appendix "E" THE "BUFFER_BEGIN" MESSAGE This message is returned when the user has tried to move the cursor passed the first element (or beginning) of buffer. This message can be safely ignored unless you want to display an error or warning. (This message is not supported by all Dialog functions). THE "ILLEGAL_POSITION" MESSAGE This message is returned when you send a "SET_POSITION" message but the position parameter is not valid. THE "NEW_POSITION" MESSAGE This message is returned when the user has moved the cursor to a new position. You can get the current position from the "Position" structure element. Every effort has been made to make these functions to be called very similarly. STRUCTURE ELEMENTS COMMON TO ALL DIALOG FUNCTIONS: The following structure elements are common to all Dialog type functions: Colors - Colors are defined using one or more of the following structure elements: Color - For functions that use only one color. Functions that use more than one color: NColor - Normal Color RColor - Reversed Color HColor - Highlight Color TColor - Color used to tag items. Screen Position - Screen coordinates are specified using one or more of the following structure elements: Row,Col - Row & column position. UpperRow,LowerRow,LeftCol,RightCol - Used in functions that must define a screen area. UpperRow/LeftCol indicate the window's top left coordinate and LowerRow/RightCol the lower right corner. Page -259- Appendix "E" EventInfo - When the user press an undefined key or an exit key it's SCAN/ASCII code value is stored in this element. ExitKeys - Pointer to a null-terminated array of unsigned integers. It must be initialized to the SCAN/ASCII code values of the keys that are to be defined as ExitKeys. (see the examples above). NOTE: ExitKeys are checked by Dialog Functions before the default editing keys. This means you can override a defined editing key or invalidate its use by defining it as an ExitKey. Position - This element holds the current cursor position. Some functions may have more than one variable. ADDITIONAL PARAMETERS Some messages (for example SET_POSITION) require that you send an additional parameter. This parameter is always the last parameter: NewPosition=123; ScrollWindow(SW_SET_POSITION,&swd,NewPosition); In this example, the new position is specified by the NewPosition variable. FUNCTIONS DERIVED FROM DIALOG FUNCTIONS Dialog functions offer a lot of power and flexibility. Several of the new functions included in this version of SCL1 utilize them. These new functions follow the general working procedure of the "INIT", "RESET", "DRAW" and "ACTIVE" messages previously described, but the retain the program control until on of the ExitKeys is pressed. In future versions of SCL1 a monitoring facility will be added to this functions to improve their flexibility. The FileBox2 and WFileBox are examples of these dialog derived functions. The next example shows how to use these functions: Page -260- Appendix "E" #include <scl1.h> main() { FBData fbd; char buffer[80]; memset(buffer,0,sizeof(buffer)); FileBox2(FB_INIT,&fbd); /* Initialize */ fbd.UpperRow=10; /* Modify size & position */ fbd.LeftCol=20; fbd.LowerRow=20; fbd.RightCol=60; fbd.Buffer=buffer; /* Use our buffer */ FileBox2(FB_DRAW,&fbd); FileBox2(FB_ACTIVE,&fbd); } Its important to know if a function is a true DIALOG function or a DIALOG-DERIVED function. Page -261- Appendix "F" CHANGES IN SCL1 version 2.0 For several reasons we have been forced to make various changes that make version 2.0 incompatible with version 1.1 in some aspects: SCL1's global variables - Some of SCL1's global variables were not originally intended to be made accessible to non-library functions, in fact some of them were not even documented. They were given names in capital letters (like MOUSE_FLAG). This can create a confusion since capital letters are generally used in C language for #define directive constants. We have changed all global variables names in order prevent this confusion . Every variable now has a prefix that identifies the function that declares the variable, for example all mouse variables start with MSE, while all Video variables declared in function VideoConfig start with VC. Following the prefix is the variable name, for example MSE_MouseFl, VC_VideoSeg etc. If you have a big program that uses a lot of these variables and you don't want to change them all you can use SCL1OLD.H header file that redefines all identifiers to new names. Take a look at this file for a complete list of modified variables. SCL1's constants - Several constants in SCL1 were not defined using uppercase as it is traditionally done in C. For example in version 1.? "LETTER" is used by GetString to accept capitalize letters while "letter" to accept letters but without capitalization. In version 2.0 all constants are uppercase. As with global variables the SCL1OLD.H file redefines all identifiers to new names. Function arguments- Several SCL1 functions received arguments of type char. Most of the times is more efficient to pass arguments of the integer type even if the extra storage space is not needed. All arguments of type char has been modified to type integer. This should not represent problems but you should not mix program modules compiled using version 1 with modules compiled with version 2. Page -262- Appendix "F" New functions- Video related - SCL1 now supports CGA 40 columns mode as well as EGA 43 lines and VGA 50 lines video modes. Video-pages are also supported. The following new functions have been added: Center DrawBoxLine DrawLine ErrorShadowOff ErrorShadowOn FillBlock Int24ShadowOff Int24ShadowOn MessageShadowOff MessageShadowOn PushCursor PopCursor SetInt24Colors SetErrorBoxColor SetDialogColor SetShadowColor SetUserBox SetUserBoxLine SetVideoMode SetVideoPage SetVideo4350 SetVideo25 VideoConfig WriteOffLen WriteOffset WriteScreenLen YesNoShadowOff YesNoShadowOn Dialog functions - This is probably the most important addition to version 2. Please refer to Dialog Functions (Appendix "E"). New functions: Calendar FieldCheck Fields2 FileBox2 LineEditor ListWindow LW_MoveTo MenuSystem MouseButton ScrollWindow Select Page -263- Appendix "F" SW_MoveTo TagList2 TextWindow Mouse functions - Double click is now supported. You can also modify the mouse cursor appearance. The InitMouse function simplifies initialization process. New functions: InitMouse ResetMouseCur SetMouseCur File functions - Several optimizations have been performed. A bug in GetFileSize that trashed the file read/write pointer was fixed. FileBox has been greatly improved and several new options are available through the use of FileBox2 and WFileBox (see Dialog functions). New functions: FindFirst FindNext Page -264- Appendix "F" REGISTRATION INFORMATION SCL1 C function Library Version 1.1 is copyrighted by José Rodríguez Alvira & José R. Lebrón. You don't have to pay any royalties to use SCL1 in your programs. To Register as a SCL1 user and to obtain a copy of SCL1 libraries for the Small, Medium, Compact, Large and Huge memory models send $30.00 (or $60.00 to also get the source code) to: José Rodríguez Alvira El Monte Sur 190, Apt. B-342, Hato Rey, Puerto Rico, 00918 You will receive by mail the latest version of the SCL1 library for the compiler of your choice, and a free copy of a Full-Screen Extended ASCII Editor called SSG, that generates the source code of your screens using SCL1's functions (The SCL1DEMO was done with the help of SSG). You will be notified of any future additions or revisions to SCL1 and of any other program developed. You are encouraged to share the Demo Distribution disk with your friends. The full version that you obtain upon registration is not intended for free distribution and should not be shared with others. The latest version of SCL1, sample programs and comments about these programs are available in: TECH BBS (Sysop: José Romero) (809)732-2322 You can leave any comments, suggestions or questions in this BBS. We will reply these messages in the same BBS. Page -265-