POINT Software Programming

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

/ POINT Software Programming / PPROG1.ISO / c / sclib31 / scl131.doc < prev next >

Wrap

Text File | 1991-12-31 | 622KB | 19,254 lines

SCL1 C - FUNCTION LIBRARY VERSION 3.1 REFERENCE MANUAL COPYRIGHT (C) 1989,1990,1991 BY: JOSE RODRIGUEZ ALVIRA AND JOSE R. LEBRON TABLE OF CONTENTS OVERVIEW . . . . . . . . . . . . . . . . . . . . . . . . . . 1 DISCLAIMER . . . . . . . . . . . . . . . . . . . . . . . . . 1 INSTALLING SCL1 . . . . . . . . . . . . . . . . . . . . . . . 2 USING SCL1 . . . . . . . . . . . . . . . . . . . . . . . . . 2 WHAT IS SSG . . . . . . . . . . . . . . . . . . . . . . . . . 3 SCL1DEMO . . . . . . . . . . . . . . . . . . . . . . . . . . 3 ALPHABETICAL REFERENCE . . . . . . . . . . . . . . . . . . . 5 APPENDIX "A" - FILE RELATED FUNCTIONS . . . . . . . . . . . 288 APPENDIX "B" - MOUSE FUNCTIONS . . . . . . . . . . . . . . . 290 APPENDIX "C" - SCREEN RELATED FUNCTIONS . . . . . . . . . . 291 APPENDIX "D" - SCL1 HEADER FILES . . . . . . . . . . . . . . 293 APPENDIX "E" - DIALOG TYPE FUNCTIONS . . . . . . . . . . . . 294 APPENDIX "F" - EXTENDED MEMORY MANAGEMENT FUNCTIONS . . . . 304 APPENDIX "G" - EXPANDED MEMORY MANAGEMENT FUNCTIONS . . . . 306 APPENDIX "H" - KEYBOARD MACROS . . . . . . . . . . . . . . . 307 APPENDIX "I" - COMMON COMPILER AND LINKER ERRORS . . . . . . 308 APPENDIX "J" - CHARACTER DEFINITION TABLES . . . . . . . . . 309 REGISTRATION INFORMATION . . . . . . . . . . . . . . . . . . 311 INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . 312 SCL1 Version 3.1 - Reference Manual - Page i OVERVIEW The functions included in this package provide an enhancement to the standard C-library functions. Extensive screen, mouse and memory handling functions are provided that are not found in the standard C 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 Microsoft and Borland C Compilers. The Shareware version contains stand alone small memory model libraries for both families of 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, large and huge (Borland version only) 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 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 a nominal distribution cost) may be charged. DISCLAIMER THE FUNCTIONS INCLUDED IN THIS PACKAGE ARE, TO THE BEST OF OUR KNOWLEDGE, ORIGINAL OR USE STANDARD ACCEPTED ALGORITHMS. 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. SCL1 Version 3.1 - Reference Manual - Page 1 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 or by Compuserve. INSTALLING SCL1 The files required to install SCL1 are distributed in compressed self-extracting files. You can use the INSTALL.EXE (not included in the Shareware version) program to perform the installation or you can manually decompress and copy them to the corresponding drives or directories. Library files are named using the following convention: MSCL1S.LIB ^ ^ | | Compiler <---------+ +------> Memory Model M = Microsoft S = Small T = Borland M = Medium C = Compact L = Large H = Huge If you are using Microsoft C or Quick C copy the library files starting with M to the drive or directory where you have your library files and the header file to the drive or directory where you have your include files. If you are using one of the Borland compilers copy the files starting with T instead. USING SCL1 To use SCL1 make sure you include the preprocessor directive "#include <SCL1.H>" in your source file. Several other header files may be needed if you use key-related constants (scl1keys.h), color definitions (scl1clor.h), expanded memory (scl1ems.h) or extended memory (scl1xms.h). See Appendix "D" for more information. You can compile your programs in two different ways: Compiling from then Command Line Be sure to specify the correct library model in the command- line. Check your compiler reference for more information. Typical command-lines can be: SCL1 Version 3.1 - Reference Manual - Page 2 cl source.c mscl1s.lib - Microsoft C qcl source.c mscl1s.lib - Microsoft Quick-C tcc source.c tscl1s.lib - Borland Turbo-C Using the Microsoft's QuickC Integrated Programming Environment Create a program list were all your source files and the LIBRARY NAME and PATH is specified. Read your compiler documentation for more information. If you are using the BorlandC or TurboC Integrated Programming Environment Create a Project File were all your source files and the LIBRARY NAME. Project files are different in the TurboC and BorlandC environments. Be sure to check your compiler's reference manual. In all cases make sure that the SCL1 library is specified and that the library's memory model matches the memory model specified to the compiler. See Appendix "I" for more information about possible errors. 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 that provides the tools for building program screens, menus, dialog screens, data entry screens, etc. 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. The SSG documentation is included in the Shareware version of SCL1. Upon registration you will receive a full working copy of SSG. The SCL1DEMO program shows some of SSG's capabilities. 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. The source code is sent with the registered version of SCL1 or you can obtain it from TECH-BBS, see the registration information at the end of this manual. SCL1 Version 3.1 - Reference Manual - Page 3 FUNCTION REFERENCE A uniform format has been used in the function reference. Functions that are related have been described together. 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 them. An index is provided at the end of the reference section. The format used is as follows: ----------------------------------------------------------------- Function Name ----------------------------------------------------------------- Purpose: A description of what the function does. Prototype: 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: An example that will further explain the function usage. Certain functions are self explanatory and do not require an example. File SCL1SAMP.EXE contains the source code for most examples. This file is included in the reagistered version of SCL1 and can be downloaded from Tech BBS. SCL1 Version 3.1 - Reference Manual - Page 4 ALPHABETICAL REFERENCE ----------------------------------------------------------------- AddExtension, ChangeExtension ----------------------------------------------------------------- Purpose: AddExtension adds an extension to a filename if it has no extension and does not end with a period. ChangeExtension changes a filename's extension or adds an extension if it has none. Prototype: char *AddExtension(char *Filename, char *Extension); char *ChangeExtension(char *Filename, char *Extension); Returns: 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); /* Add an extension to file */ printf("%s\n",AddExtension(Filename,"C")); /* Change extension from "TXT" to "BAK"*/ ChangeExtension(Filename,"BAK"); printf("%s\n",Filename); } See also RemoveExtension SCL1 Version 3.1 - Reference Manual - Page 5 BackgroundOff ----------------------------------------------------------------- BackgroundOff ----------------------------------------------------------------- Purpose: Stops a function running in the background. Prototype: void BackgroundOff(void); Returns: Nothing Parameters: None Example: #include <process.h> #include <stdlib.h> #include <errno.h> #include <scl1.h> #include <scl1clor.h> /* BackgroundOn/Off example. Displays a clock in top right corner of the screen */ int hours,minutes,seconds; char buffer[12]; int BackClock(void); main() { char *p; Cls(WHITE_BLACK,CLS_ALL); GetTime(); hours=GT_Hours; minutes=GT_Minutes; seconds=GT_Seconds; SetCurPos(2,0); printf("A background clock will be active until you type EXIT\n"); BackgroundOn(BackClock); /* set background function */ p=getenv("COMSPEC"); /* run command.com */ SCL1 Version 3.1 - Reference Manual - Page 6 BackgroundOff if(p) { if(spawnl(P_WAIT,p,0)) { if(errno == ENOMEM) printf("\nNot enough memory to load COMMAND.COM\n"); else printf("\nUnable to load COMMAND.COM\n"); } } else printf("\nEnvironment Variable COMPSEC not found\n"); BackgroundOff(); /* stop background process */ ClearKeyBuf(); } #pragma check_stack(off) /* this function will be called 18.2 per second */ int BackClock(void) { int i; static int count=18; /* count variable is used to keep track of time. When count= 18, a second has elapsed */ if(count==18) { ++seconds; if(seconds == 60) { seconds=0; ++minutes; if(minutes == 60) { minutes=0; ++hours; if(hours == 24) hours=0; } } i=0; SCL1 Version 3.1 - Reference Manual - Page 7 BackgroundOff /* convert hours/minutes/seconds values to ASCII */ if(hours < 10) { buffer[i]='0'; ++i; } itoa(hours,buffer+i,10); i=3; if(minutes < 10) { buffer[i]='0'; ++i; } itoa(minutes,buffer+i,10); i=6; if(seconds < 10) { buffer[i]='0'; ++i; } itoa(seconds,buffer+i,10); buffer[2]=':'; buffer[5]=':'; count=0; } else ++count; Box(BLACK_WHITE,0,0,69,2,78); WriteScreen(BLACK_WHITE,70,buffer); } Note: It is very important to stop any background function before returning to DOS. Failure to do so can result in a system crash. See also BackgroundOn. SCL1 Version 3.1 - Reference Manual - Page 8 BackgroundOn - Beep - BigCursor ----------------------------------------------------------------- BackgroundOn ----------------------------------------------------------------- Purpose: Makes a function share microprocessor time with a main process (run in the background). Prototype: void BackgroundOn(int (*FAddress)()); Returns: Nothing Parameter: FAddress - Pointer to the function that will be set to run in the background. Example: See BackgroundOff Note: Functions that run in the background must not perform disk or keyboard input/output or call any time or sound related function. SCL1's screen related functions (except GSSBox) and the standard library data manipulation functions are generally safe for 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. With a Microsoft compiler you might need to disable the compiler's stack checking option using the "#pragma check_stack(off)" directive. ----------------------------------------------------------------- Beep ----------------------------------------------------------------- Purpose: Sends a beep tone to the console speaker. Prototype: void Beep(void); Returns: Nothing Parameters: None See also SoundOn, SoundOff and TSound ----------------------------------------------------------------- BigCursor ----------------------------------------------------------------- Purpose: Changes the cursor size to a block. Prototype: void BigCursor(void); Returns: Nothing Parameters: None SCL1 Version 3.1 - Reference Manual - Page 9 Bin2Ascii ----------------------------------------------------------------- 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 null string terminating character. Prototype: char *Bin2Ascii(long Number,char * Buffer); Returns: 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(); } } See also SetBin2AsciiDel SCL1 Version 3.1 - Reference Manual - Page 10 Box - GSSBox ----------------------------------------------------------------- Box, GSSBox ----------------------------------------------------------------- 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. It does not perform bound checking, the box will spill out of the screen area if the coordinates are outside the screen range. It draws only the box's frame and does not fill the box's interior. GSSBox draws a box frame and fills its interior. Three flags; Grow, Noise and Shadow can be specified. The grow flag tells the function to draw the box with a growing effect, the noise flag to make a swirling noise when drawing the box, and the shadow flag 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. Leave space for the shadow characters. You can define other types of frames using SetUserBox. Prototype: void Box(int Color,int FrameType,int UpperRow, int LeftCol,int LowerRow, int RightCol); 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 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* ██████████ ********** SCL1 Version 3.1 - Reference Manual - Page 11 Box - GSSBox UpperRow - upper row position of the box (integer). LeftCol - left column position of the box (integer). LowerRow - lower row position of the box (integer). RightCol - right column position of the box (integer). (Note: the home position is row 0, column 0.) For GSSBox only: GrowFl - flag to indicate a growing effect. 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 indicate a noise effect. 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 indicate 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() { 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.*/ GSSBox(Color1,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 Shadow and SetShadowColor SCL1 Version 3.1 - Reference Manual - Page 12 Buf2Disk - HBuf2Disk ----------------------------------------------------------------- Buf2Disk, HBuf2Disk ----------------------------------------------------------------- Purpose: Saves a buffer to disk. With HBuf2Disk the file size can be larger than 64K, using the compact and large models. HBuf2Disk's prototype is declared in SCL1HUGE.H Prototype: int Buf2Disk(char* Filename, char *Buffer, unsigned int Bytes); int HBuf2Disk(char* Filename,char huge *Buffer, unsigned long Bytes); Returns: The DOS error code or "0" if no error occurs. (See Appendix "A", FILE FUNCTIONS, for more information). Parameters: Filename - filename of file to write data to (char pointer). Buffer - buffer that holds the data to be written to disk. Bytes - the number of bytes to write (unsigned integer for Buf2Disk and unsigned long for HBuf2Disk). 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, HFile2Buf and TrapInt24. SCL1 Version 3.1 - Reference Manual - Page 13 Calendar ----------------------------------------------------------------- Calendar ----------------------------------------------------------------- Purpose: Displays a calendar. It can display it either in english, spanish or in any other language set by using the C_SetUserLang function. The calendar position can be set anywhere in the screen. No bounds checking is made. Prototype: 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. It returns messages as described below. Parameters: Dialog type functions receive messages and structures as parameters. The calendar information is defined in structure CData as follows: typedef struct{ int NColor; Normal color for the calendar display. int RColor; Color for displaying the selected day. int Row; Upper left row position of the calendar. int Col; Upper left column position of the calendar. int FrameType; Type of frame to be used, any of the frame types that can be used with Box. unsigned int *ExitKeys; Null-terminated array of keys that will exit the calendar function. int Lang; Language. "0" for english, "1" for spanish, "2" for any other language (define the text with C_SetUserLang). int Month; Month to be displayed. int Day; Day to be displayed (1-31). int Year; Year to be displayed from 1900 to 2067. SCL1 Version 3.1 - Reference Manual - Page 14 Calendar unsigned int EventInfo; Variable that holds the key pressed when you exit the function or a when a non defined key is pressed. }CData; Messages: The following messages can be sent to Calendar: C_INIT - initialize the CData structure to NULL and set the following default values: NColor - white characters in a black background or the normal color set by SetDialogColors. HColor - highlighted white characters in a black background or the highlight color set by SetDialogColors. Col and Row - for display it in the middle of the screen. Month, Day and Year - current system's date. FrameType - frame type "0" (double line). ExitKeys - defined as ENTER, ESCAPE, TAB & SHIFTAB. C_DRAW - display the calendar using the current parameters. C_ACTIVE - display the calendar with the current parameters and let the user change the date using the cursor 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. The date can also be changed by clicking the mouse buttons in the calendar display. C_CHECK_MOUSE - asks the function if the mouse has been clicked while pointing the calendar area. SCL1 Version 3.1 - Reference Manual - Page 15 Calendar C_SHADOW_ON - displays a shadow effect when the calendar is drawn. C_SHADOW_OFF - disables the shadow effect. C_RESET - when this message is sent the Day, Month and Year variables are set to the system's date. If 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 */ }while (Mess!=C_EXIT_KEY); } SCL1 Version 3.1 - Reference Manual - Page 16 Center - ChangeDumpColor ----------------------------------------------------------------- Center ----------------------------------------------------------------- Purpose: Centers a string horizontally. Prototype: int Center(char *String); Returns: The column position required for displaying the string centered in the screen. Parameter: String - pointer to the string to be centered (char). Example: #include <scl1.h> main() { WriteString(0x7,1,Center("Main Menu"),"Main Menu"); } ----------------------------------------------------------------- ChangeDumpColor ----------------------------------------------------------------- Purpose: Changes the color attributes of a ScreenDump array. Prototype: 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> /* Each character is followed by its color attribute, a \n can be used to indicate new lines and a "0" is used to indicate the end of the array */ char Array[]={'A',7,'B',0x70,\n,'C',0x70,'D',7,0}; SCL1 Version 3.1 - Reference Manual - Page 17 ChangeDumpColor - CheckChar main() { ScreenDump(10,10,Array); /* Write at line 10, column 10 */ GetKey(); ChangeDumpColor(0x70,7,Array);/*Change color from 0x70 to 7*/ ScreenDump(10,10,Array); /* Write at line 10, column 10 */ } See also ScreenDump. ----------------------------------------------------------------- CheckChar ----------------------------------------------------------------- Purpose: Checks for a valid keyboard character. Prototype: 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. SCL1 Version 3.1 - Reference Manual - Page 18 CheckChar - CheckEnhancedKeyb 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 */ } ----------------------------------------------------------------- CheckEnhancedKeyb ----------------------------------------------------------------- Purpose: After this function is called and an enhanced keyboard (101 keys) is detected, SCL1's keyboard related functions will return different SCAN/ASCII codes for the extra keys found in these keyboards (for example; the ENTER key in the numeric keypad and the regular ENTER key). These codes have been defined in SCL1KEYS.H preceded by the ENH prefix. This function also enables the detection of the F11 and F12 function keys. Prototype: int CheckEnhancedKeyb(void); Returns: The return value is "1" of an enhanced keyboard is detected or "0" if none is detected. Example: #include <scl1.h> #include <scl1keys.h> /* shows the use of CheckEnhancedKeyb function */ main() { unsigned int Key; if(CheckEnhancedKeyb()) printf("\nAn enhanced keyboard has been detected\n Press one of your ENTER keys\nor functions keys F11-F12\nESC to exit\n"); SCL1 Version 3.1 - Reference Manual - Page 19 CheckEnhancedKeyb else { printf("No Enhanced Keyboard available\n"); exit(-1); } /* SCL1 keyboard function will now report enhanced keyboard extra keys */ do { switch(Key=GetKey()) { case ENH_ENTER: printf("Enhanced Enter, press the other ENTER key\n"); break; case ENTER: printf("Enter, press the other ENTER key\n"); break; case F11: printf("F11\n"); break; case F12: printf("F12\n"); break; case SHIFTF11: printf("Shift F11\n"); break; case SHIFTF12: printf("Shift F12\n"); break; case CTRLF11: printf("Control F11\n"); break; case CTRLF12: printf("Control F12\n"); break; case ALTF11: printf("Alt F11\n"); break; case ALTF12: printf("Alt F12\n"); break; default: printf("Unknown key SCAN/ASCII Code: %X\n",Key); break; } }while(Key != ESC); } SCL1 Version 3.1 - Reference Manual - Page 20 CheckItemList ----------------------------------------------------------------- CheckItemList ----------------------------------------------------------------- Purpose: Checks if the mouse has been clicked at any item in an item list (SEE DrawItemList). Prototype: int CheckItemList(int Number, int ItemLength, struct ItemList *il); Returns: The number of the item selected with the mouse (>"1") or "0" if none has been selected. Parameters: The item list information is given as an array of structures as follows: struct ItemList{ int Row; Row position of the item. int Col; Column position of the item. char *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. 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 SCL1 Version 3.1 - Reference Manual - Page 21 CheckItemList - CheckMouse { printf("No Mouse Installed\n"); exit(-1); } DrawItemList(WHITE_BLACK,BLACK_WHITE,3,Selection,il); SetCurPos(14,0); while(Selection==0) { if(Selection=CheckItemList(3,8,il)) { DrawItemList(WHITE_BLACK,BLACK_WHITE,3,Selection,il); printf("\nOption #%i was selected\n",Selection); } } exit(0); } 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. ----------------------------------------------------------------- CheckMouse ----------------------------------------------------------------- Purpose: Determines if a mouse is installed. Sets variable MSE_MouseFl to "1" if mouse is found. Prototype: int CheckMouse(void); Returns: The return value is "1" if the mouse is installed and "0" if no mouse is installed. Parameters: None Example: #include <scl1.h> main() {if(CheckMouse())/* do we have a mouse? */ { /* Yes */ ResetMouse(); /* reset mouse */ SetMouseIsr();/* initialize ISR */ ShowMouse(); /* cursor on */ } ResetMouse(); /* reset mouse before exit */ } SCL1 Version 3.1 - Reference Manual - Page 22 CheckMouseButton ----------------------------------------------------------------- CheckMouseButton ----------------------------------------------------------------- Purpose: Checks if the mouse has been clicked at any mouse button defined using the DrawMouseButton function. Prototype: int CheckMouseButton(int Number, struct MouseButton *p); Returns: The number of the selected screen Mouse Button or "0" if none has been selected. Parameters: The Mouse Button information is specified in a structure as follows: struct MouseButton{ int Top; Upper row position of the Mouse Button area. int Left; Upper column position of the Button area. int Bottom; Right row position of the Button area. int Right; Right column position of the Button area. int Row; Row position of the Mouse Button text. int Col; Column position of the Button text. char String[20]; Mouse Button text (maximum of 19 characters.). }; The parameters passed to the function are: Number - number of mouse buttons (integer). MouseButton - pointer to defined structure. Example: #include <scl1.h> #include <scl1clor.h> SCL1 Version 3.1 - Reference Manual - Page 23 CheckMouseButton - ClearKeyBuf struct MouseButton mb[]={ 4,35,6,45, 5,39, "YES", 10,35,12,45, 11,39, "NO",}; main() { int Selection=0; Cls(WHITE_BLACK,CLS_ALL); if(CheckMouse()) InitMouse(IM_SHOW); else { printf("No Mouse Installed\n"); exit(-1); } DrawMouseButton(WHITE_BLACK,BLACK_WHITE,2,Selection,mb); SetCurPos(14,0); while(Selection==0) { if(Selection=CheckMouseButton(2,mb)) { DrawMouseButton(WHITE_BLACK,BLACK_WHITE,2,Selection,mb); printf("\nMouse button #%i was selected\n",Selection); } } exit(0); } See also DrawMouseButton to draw the buttons. ----------------------------------------------------------------- ClearKeyBuf ----------------------------------------------------------------- Purpose: Clears keyboard buffer of any character or keystroke pending to be processed. Prototype: void ClearKeyBuf(void); Returns: Nothing. Parameters: None. SCL1 Version 3.1 - Reference Manual - Page 24 ClearWindow - ClockTick ----------------------------------------------------------------- ClearWindow ----------------------------------------------------------------- Purpose: Clears a window previously defined using the InitWdata function and displayed using the CreateWindow function. Prototype: void ClearWindow(WData *wd); Returns: Nothing Parameter: WData - pointer to the WData structure. Example: See InitWData ---------------------------------------------------------------- ClockTick ---------------------------------------------------------------- Purpose: When this function is called the program waits for the next timer interrupt before returning control to the calling program or function. Prototype: void ClockTick(void); Returns: Nothing Parameters: None SCL1 Version 3.1 - Reference Manual - Page 25 CloseFile ----------------------------------------------------------------- CloseFile ----------------------------------------------------------------- Purpose: Closes a file. Prototype: int CloseFile(int Handle); Returns: The DOS error code or "0" if no error occurs. (See Appendix "A", FILE FUNCTIONS, for more information). Parameter: Handle - Handle number 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)); } SCL1 Version 3.1 - Reference Manual - Page 26 Cls ----------------------------------------------------------------- Cls ----------------------------------------------------------------- Purpose: Clears a screen area. Prototype: 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 position of the area to be cleared (integer). Valid range from 0 to 24. LeftCol - left column position of the area to be cleared (integer). Valid range from 0 to 79. LowerRow - lower row position of the area to be cleared. (int). RightCol - right column position of the area to be cleared. (int). 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.*/ } SCL1 Version 3.1 - Reference Manual - Page 27 CreateFile ----------------------------------------------------------------- CreateFile ----------------------------------------------------------------- Purpose: Creates a new file or truncates an existing file to zero. Prototype: int CreateFile(char *Filename,int *Handle, int Attrib); Returns: the DOS error code or "0" if no 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 will contain 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: See CloseFile SCL1 Version 3.1 - Reference Manual - Page 28 CreateWindow - DestroyWindow - CursorOn - CursorOff ----------------------------------------------------------------- CreateWindow, DestroyWindow ----------------------------------------------------------------- Purpose: CreateWindow displays a window defined with a WData structure that can be initialized using the InitWdata function. This function can save the screen area in a buffer, draw a frame, shadow, grow, shrink, etc. These attributes are specified when the WData struct is initialized. DestroyWindow removes or deletes a window previously defined using the CreateWindow function and restores the screen. Prototype: int CreateWindow(WData *wd); void DestroyWindow(WData *wd); Returns: CreateWindow can return one of the following messages defined in header file SCL1.H: W_OK if the window was created. W_NOMEM if there is not enough memory left for the window buffer. DestroyWindow does not return values. Parameter: WData - pointer to the WData structure. Example: See InitWData ----------------------------------------------------------------- CursorOff, CursorOn ----------------------------------------------------------------- Purpose: Turns the cursor off (not visible), or on (visible). Prototype: void CursorOff(void); void CursorOn(void); Returns: Nothing Parameters: None SCL1 Version 3.1 - Reference Manual - Page 29 C_SetUserLang ----------------------------------------------------------------- C_SetUserLang ----------------------------------------------------------------- Purpose: Lets you modify the month and week day names for the Calendar function. Prototype: void C_SetUserLang(CData *cd,char **data); Returns: Nothing. Parameters: cd - pointer to the Calendar structure. data - array that contains the user defined month names and week names (refer to the example). Example: /* months and weeks days in French */ char *month[]={ "Janvier", "Fevrier", "March", "Avril", "May", "June", "Julliet", "Aout", "September", "October", "Novembre", "Decembre", " Dim Lun Mar Mer Jeu Ven Sam ", /* spaces are important */ }; /* A sample call to the function will be: */ C_SetUserLang(&cd,month); SCL1 Version 3.1 - Reference Manual - Page 30 Date2Num ----------------------------------------------------------------- Date2Num ----------------------------------------------------------------- Purpose: Converts a date in the format Month-Day-Year to an unsigned integer number that represents the number of days the have elapsed since the base date (January 1, 1900, which corresponds to number 1). This conversion saves storage space since the date is represented as an unsigned integer. This function together with Num2Date permits you to perform date arithmetic, like adding x number of days to a date, etc. Prototype: unsigned int Date2Num(int Month, int Day, int Year); Returns: An unsigned integer which represents the date or "0" if an invalid date is passed to the function. Parameters: Month - a valid month number (1 to 12) (integer). Day - a valid day number (1 to 28,29,30 or 31) (integer). Year - a valid year number (four digits) from 1900 to 2077 (int). Example: #include <scl1.h> main() { int D,M,A,W; unsigned int N; scanf("%i",&M); scanf("%i",&D); scanf("%i",&A); N=Date2Num(M,D,A); if(N==0) printf("Invalid Date"); else { printf(" %ui\n",N); Num2Date(N,&M,&D,&A,&W); printf(" %i,%i,%i %i",M,D,A,W); } } See also Num2Date SCL1 Version 3.1 - Reference Manual - Page 31 DaysPerMonth - DeleteFile ----------------------------------------------------------------- DaysPerMonth ----------------------------------------------------------------- Purpose: Returns the number of days of a given month. Prototype: int DaysPerMonth(int year,int month); Returns: The number of days that a given month contains. Parameters: Year - valid month year (4 digits) from 1900 to 2077 (int). Month - a valid month number (1 to 12) (integer). ----------------------------------------------------------------- DeleteFile ----------------------------------------------------------------- Purpose: Deletes a file. Prototype: int DeleteFile(char *Filename); Returns: The DOS error code or "0" if no error occurs. (See Appendix "A", FILE FUNCTIONS, for more information). Parameter: Filename - char pointer to a valid filename. Example: #include <scl1.h> main() { int handle,i; i=CreateFile("SCL1.TST",&handle,F_ARCHIVE); if(i) { printf("\nDOS error #%i, unable to create file\n",i); exit(-1); } CloseFile(handle); i=DeleteFile("SCL1.TST"); if(i) { printf("\nDOS error #%i, unable to erase file\n",i); exit(-1); } exit(0); } SCL1 Version 3.1 - Reference Manual - Page 32 DialogBox ----------------------------------------------------------------- DialogBox ----------------------------------------------------------------- Purpose: Displays a dialog box at the center of the screen for keyboard input. The function takes care or saving and restoring the screen contents in the display area. See the GetString function for the editing features. Prototype: int DialogBox(int BoxColor,char *Prompt, int InputColor,int MaxChar, unsigned int CharType,char *Buffer); Returns: 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> char buffer[33] /* buffer to hold input, one character larger than MaxChar */ /* The following function call will display the DialogBox */ DialogBox(WHITE_BLACK,"Filename",BLACK_WHITE,32,CC_FILESPEC, buffer); SCL1 Version 3.1 - Reference Manual - Page 33 DisableMouse - Dissolve ----------------------------------------------------------------- DisableMouse ----------------------------------------------------------------- Purpose: Removes interrupt service routine installed by SetMouseIsr Prototype: void DisableMouse(void); Returns: Nothing Parameters: None Example: See CheckMouse ----------------------------------------------------------------- Dissolve ----------------------------------------------------------------- Purpose: Clears the screen using special effects like; shrink from borders to the center, horizontal shrink from borders to center, etc. The function works in all video modes supported by SCL1. Prototype: void Dissolve(int Color,int Type,int Speed); Returns: Nothing Parameters: Color - color to be used for clearing the screen (integer). Type - the clearing effect to use (integer). The following types have been defined in SCL1.h: DS_BOX - use a shrinking effect from borders to center. DS_SIDES - use an horizontal shrinking effect from borders to the center. DS_SIX_PARTS - use an horizontal shrinking effect from left to right in six screen sections. DS_FOUR_BOXES - same effect as DS_BOX but provides four sections. Speed - speed to use for the clearing effect in hundredths of a second (integer). The recommended speed is 1 hundredths of a second. SCL1 Version 3.1 - Reference Manual - Page 34 Dissolve Example: #include <scl1.h> #include <scl1clor.h> /* Shows several dissolve effects for clearing the screen */ main() { int Color1,Color2; if(Video()==COLOR) { Color1=WHITE_BLACK; Color2=BROWN_BLACK+HIGHLIGHT; } else { Color1=WHITE_BLACK; Color2=WHITE_BLACK+HIGHLIGHT; } /* Fill screen with X */ FillBlock(Color2,0,0,VC_Lines-1,VC_Cols-1,'X'); WaitTime(50); /* 1/2 second delay */ Dissolve(Color1,DS_BOX,1); /* Clear screen */ WaitTime(50); FillBlock(Color2,0,0,VC_Lines-1,VC_Cols-1,'X'); WaitTime(100); Dissolve(Color1,DS_SIDES,1); WaitTime(50); FillBlock(Color2,0,0,VC_Lines-1,VC_Cols-1,'X'); WaitTime(100); Dissolve(Color1,DS_SIX_PARTS,1); WaitTime(50); FillBlock(Color2,0,0,VC_Lines-1,VC_Cols-1,'X'); WaitTime(100); Dissolve(Color1,DS_FOUR_BOXES,1); } SCL1 Version 3.1 - Reference Manual - Page 35 DrawBoxLine ----------------------------------------------------------------- DrawBoxLine ----------------------------------------------------------------- Purpose: Draws either vertical or horizontal lines inside a box with the proper end line characters. Prototype: void DrawBoxLine(int Color,int FrameType,int Row1, int Col1,int Row2,int Col2); Returns: Nothing Parameters: 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 SCL1 Version 3.1 - Reference Manual - Page 36 DrawItemList ----------------------------------------------------------------- DrawItemList ----------------------------------------------------------------- Purpose: Draws a list of strings to the screen and permits the user to browse through them. The selected item (>0) is drawn in the color specified with SelectedColor. Prototype: 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; Row position of the item. int Col; Column position of the item. char *String; Char pointer to item text. }; The parameters passed to the function are: NormalColor - color for the normal display of items (integer). SelectedColor - color 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. Example: See CheckItemList NOTE: The ScrollWindow and ListWindow functions provide alternatives to perform the same tasks. SCL1 Version 3.1 - Reference Manual - Page 37 DrawLine ----------------------------------------------------------------- DrawLine ----------------------------------------------------------------- Purpose: Draws either vertical or horizontal lines. Prototype: void DrawLine(int Color,int Row,int Col,int Count, int Direction,int Character); Returns: Nothing Parameters: 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. Constants DL_HORIZONTAL and DL_VERTICAL has been defined in SCL1.H. Character - graphic character to use for line drawing (int). 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 */ } SCL1 Version 3.1 - Reference Manual - Page 38 DrawMouseButton ----------------------------------------------------------------- DrawMouseButton ----------------------------------------------------------------- Purpose: Draws one or more Mouse Buttons. The selected button is drawn inside a double line box. A mouse button consists of a text prompt inside a box. You can select the mouse button by clicking the mouse after pointing it. Prototype: void DrawMouseButton(int NormalColor, int SelectedColor,int Number,int Selection, struct MouseButton *p); Returns: Nothing. Parameters: The Mouse Button information must be given as an array of structures: struct MouseButton{ int Top; Upper row position of the Mouse Button area. int Left; Upper column position of the Mouse Button area. int Bottom; Right row position of the Mouse Button area. int Right; Right column position of the Mouse Button area. int Row; Row position of the Mouse Button text. int Col; Column position of the Mouse Button text. char String[20]; Mouse Button text (19 characters maximum) }; The parameters passed to the function are: NormalColor - color used when button is not selected 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) (int). MouseButton - pointer to predefined structure. Example: See CheckMouseButton SCL1 Version 3.1 - Reference Manual - Page 39 EB_SetUserLang ----------------------------------------------------------------- EB_SetUserLang ----------------------------------------------------------------- Purpose: Lets you modify the default prompts of the ErrorBox function. With it you can customize the default "Press any key to Continue" and "Unknown Error" prompts. This is useful when writing programs in languages other that English. Error messages can be defined using the InitUserError function. See ErrorBox for default messages. Prototype: void EB_SetUserLang(char *prompt1,char *prompt2); Returns: Nothing. Parameters: prompt1 - char pointer to the first prompt, whose default is "Press any key to Continue". prompt2 - char pointer to the second prompt, whose default is "Unknown Error". Example: /* this function call sets the ErrorBox prompts to Spanish */ EB_SetUserLang("Oprima cualquier tecla para Continuar","Error Desconocido"); SCL1 Version 3.1 - Reference Manual - Page 40 EMS_Alloc ----------------------------------------------------------------- EMS_Alloc ----------------------------------------------------------------- Purpose: Allocates the number of pages requested and assigns an EMM handle to these pages. The EMM handle owns these pages until they are deallocated. Prototype: int EMS_Alloc(int handle,int pages); Returns: Returns one of the following messages defined in header file SCL1EMS.H: EMS_OK if EMS has allocated the requested pages. EMS_NOT_IMPLEMENTED if the function code passed to the memory manager is not defined. EMS_INTERNAL_ERROR if a malfunction in the memory manager software is detected. EMS_HARDWARE_ERROR if a malfunction in the expanded memory hardware is detected. EMS_NO_MORE_HANDLE if all EMM handles are being used. EMS_LOG_GREATER_PH if there are not enough expanded memory pages present in the system to satisfy the request. EMS_LOG_GREATER_AVA if there are not enough unallocated pages to satisfy the request. EMS_ZERO_ALLOC if you attempted to allocate zero pages. Parameters: handle - the EMM handle your program received from a call to the EMS_Alloc function (integer). pages - the number of pages you want your program to allocate (integer). Example: See EMS_Init SCL1 Version 3.1 - Reference Manual - Page 41 EMS_AvailableLogPages ----------------------------------------------------------------- EMS_AvailableLogPages ----------------------------------------------------------------- Purpose: Returns the number of unallocated pages of expanded memory. Prototype: int EMS_AvailableLogPages(unsigned int *npages); Returns: Returns one of the following messages defined in header file SCL1EMS.H: EMS_OK if EMS has returned the number of unallocated pages and the number of total pages in expanded memory. EMS_NOT_IMPLEMENTED if the function code passed to the manager is not defined. EMS_INTERNAL_ERROR if a malfunction in the memory manager software is detected. EMS_HARDWARE_ERROR if a malfunction in the expanded memory hardware is detected. Parameter: npages - pointer to an unsigned int that will be set to the number of currently available pages (unallocated). Example: See EMS_Init SCL1 Version 3.1 - Reference Manual - Page 42 EMS_Exchange - EMS_Move ----------------------------------------------------------------- EMS_Exchange, EMS_Move ----------------------------------------------------------------- Purpose: Exchanges or moves a region of memory from conventional to conventional memory, conventional to expanded memory, expanded to conventional memory or expanded to expanded memory. Prototype: int EMS_Exchange(EMSMove *); int EMS_Move(EMSMove *); Returns: Returns one of the following messages defined in header file SCL1EMS.H: EMS_OK if the memory regions have been exchanged or moved. EMS_NOT_IMPLEMENTED if the function code passed to the EMS manager is not defined. EMS_INTERNAL_ERROR if a malfunction in the memory manager software is detected. EMS_HARDWARE_ERROR if a malfunction in the expanded memory hardware is detected. EMS_INVALID_HANDLE if the manager could not find either the source or destination EMM handles. EMS_INVALID_LOG if one or more of the logical pages is out of the range of logical pages allocated to the source/destination handle. EMS_S_NOT_IMPLEMENTED if EMS subfunction is invalid. EMS_SOURCE_OVERWRITTEN if the source and destination expanded memory regions have the same handle and overlap. This is valid for a move. The move has been completed and the destination region has a copy of the source region. However, at least a portion of the source region has been overwritten by the move. EMS_SIZE_ERROR if the length of the source or destination expanded memory region specified exceeds the length of the expanded memory region allocated either the source or destination handle. EMS_OVERLAP if the conventional memory region and expanded memory region overlap. SCL1 Version 3.1 - Reference Manual - Page 43 EMS_Exchange - EMS_Move EMS_OFFSET_ERROR if the offset within the logical page exceeds the length of the logical page. EMS_TOO_BIG if a region length exceeds 1M byte. EMS_UNDEFINED_TYPE if the memory source and destination types are undefined. EMS_WRAP_ERROR if an attempt was made to wrap around the 1M-byte address space of conventional memory during the move. EMS_OVERLAP_ERROR if the source and destination expanded memory regions have the same handle and overlap. Parameter: The parameter is a pointer to a an EMSMove structure as follows: typedef struct{ unsigned long bytes; Specifies the length of the memory region to be exchanged or moved. char stype; Type of memory where the source region resides. EMS_CONVENTIONAL_MEM indicates that the source region resides in conventional memory. EMS_EXPANDED_MEM indicates that the source region resides in expanded memory. unsigned int shandle; If the source region resides in expanded memory, shandle specifies the handle number associated with the source memory region. If the source region resides in conventional memory, shandle has no meaning and should be set to zero. unsigned int soffset; Specifies the offset within the source region from which to do the exchange or move. If the source region resides in expanded memory, this offset is relative to the beginning of the 16K logical page. If the source region resides in conventional memory, soffset specifies the offset, relative to the beginning of the source segment, from which to do the exchange or move. SCL1 Version 3.1 - Reference Manual - Page 44 EMS_Exchange - EMS_Move unsigned int sseg; Specifies the initial segment or logical page number within the source region from which to do the exchange or move. If the source region resides in expanded memory, sseg specifies the logical page within the source region from which to do the exchange or move. If the source region resides in conventional memory, sseg specifies the initial segment address within conventional memory from which to do the exchange or move. char dtype; Specifies the type of memory where the destination region resides. unsigned int dhandle; If the destination region resides in expanded memory, dhandle specifies the handle number associated with the destination memory region. If the destination region resides in conventional memory, dhandle has no meaning and should be set to zero. unsigned int doffset; specifies the offset within the destination region from which to do the exchange or move. If this region resides in expanded memory, doffset is relative to the beginning of the logical page. If the destination region resides in conventional memory, doffset specifies the offset, relative to the beginning of the destination segment, to do the exchange or move. unsigned int dseg; specifies the initial segment or logical page number within the destination region from which to do the exchange or move. If the destination region resides in expanded memory then dseg specifies the logical page within the destination region from which to do the exchange or move. If the destination region resides in conventional memory, dseg specifies the initial segment address within conventional memory from which to do the exchange or move. }EMSMove; Example: See EMS_Init SCL1 Version 3.1 - Reference Manual - Page 45 EMS_Free ----------------------------------------------------------------- EMS_Free ----------------------------------------------------------------- Purpose: Deallocates the logical pages currently allocated to an EMM handle. Only after the application deallocates these pages can other applications use them. When a handle is deallocated, its name is set to all ASCII nulls (binary zeros). A program must perform this function before it exits to DOS. If it doesn't, no other programs can use these pages or the EMM handle. Prototype: int EMS_Free(int handle); Returns: Returns one of the following messages defined in header file SCL1EMS.H: EMS_OK if EMS has deallocated the requested pages previously allocated. EMS_NOT_IMPLEMENTED if the function code passed to the memory manager is not defined. EMS_INTERNAL_ERROR if a malfunction in the memory manager software is detected. EMS_HARDWARE_ERROR if a malfunction in the expanded memory hardware is detected. EMS_INVALID_HANDLE if the specified EMM handle cannot be found. EMS_SAVE_REST_ERROR if the memory manager detected a save or restore page mapping context error (EMS_SavePageMap or EMS_RestorePageMap functions); Parameter: handle - EMM handle. This handle is returned by the EMS_Alloc function. Example: See EMS_Init SCL1 Version 3.1 - Reference Manual - Page 46 EMS_GetAllHandlePages ----------------------------------------------------------------- EMS_GetAllHandlePages ----------------------------------------------------------------- Purpose: Returns an array of the open EMM handles and the number of pages allocated to each one. Prototype: int EMS_GetAllHandlePages(EMSHandle *p,int *entries); Returns: Returns one of the following messages defined in header file SCL1EMS.H: EMS_OK if EMS has returned the array. EMS_NOT_IMPLEMENTED if the function code passed to the manager is not defined. EMS_INTERNAL_ERROR if a malfunction in the memory manager software is detected. EMS_HARDWARE_ERROR if a malfunction in the expanded memory hardware is detected. Parameters: The parameter is a pointer to a an EMSHandle structure as follows: typedef struct{ unsigned int handle; Contains the value of the open EMM handle. The values of the handles this function returns will be in the range of 0 to 255 decimal (0000h to 00FFh). The uppermost byte of the handle is always zero. unsigned int pages; Contains the number of pages allocated to the open EMM handle. }EMSHandle; Parameter: entries - pointer to an integer value that will be set to the number of open EMM handles (including the operating system handle [0]). The number cannot be zero because the operating system handle is always active and cannot be deallocated. This number will not exceed 255. Example: See EMS_Init SCL1 Version 3.1 - Reference Manual - Page 47 EMS_GetHandleCount ----------------------------------------------------------------- EMS_GetHandleCount ----------------------------------------------------------------- Purpose: Returns the number of open EMM handles (including the operating system handle 0) in the system. Prototype: int EMS_GetHandleCount(int *ActiveHandles); Returns: Returns one of the following messages defined in header file SCL1EMS.H: EMS_OK if EMS has returned the number of active EMM handles. EMS_NOT_IMPLEMENTED if the function code passed to the manager is not defined. EMS_INTERNAL_ERROR if a malfunction in the memory manager software is detected. EMS_HARDWARE_ERROR if a malfunction in the expanded memory hardware is detected. Parameter: ActiveHandles - pointer to an integer value that will be set to the number of open EMM handles [including the operating system handle (0)].This number will not exceed 255. Example: See EMS_Init SCL1 Version 3.1 - Reference Manual - Page 48 EMS_GetHandleName ----------------------------------------------------------------- EMS_GetHandleName ----------------------------------------------------------------- Purpose: Gets the eight character name currently assigned to a handle. There is no restriction on the characters which may be used in the handle name. Prototype: int EMS_GetHandleName(int handle,char *name); Returns: Returns one of the following messages defined in header file SCL1EMS.H: EMS_OK if EMS has returned the handle name. EMS_NOT_IMPLEMENTED if the function code passed to the manager is not defined. EMS_INTERNAL_ERROR if a malfunction in the memory manager software is detected. EMS_HARDWARE_ERROR if a malfunction in the expanded memory hardware is detected. EMS_INVALID_HANDLE if EMS couldn't find the EMM handle your program specified. EMS_S_NOT_IMPLEMENTED if an EMS subfunction is invalid Parameters: handle - contains the EMM handle (integer). name - pointer to an array which will be set to the name associated with the specified handle. Example: See EMS_Init SCL1 Version 3.1 - Reference Manual - Page 49 EMS_GetHandlePages ----------------------------------------------------------------- EMS_GetHandlePages ----------------------------------------------------------------- Purpose: Returns the number of pages allocated to a specific EMM handle. Prototype: int EMS_GetHandlePages(int Handle,int *Pages); Returns: Returns one of the following messages defined in header file SCL1EMS.H: EMS_OK if EMS has returned the number of pages allocated to the EMM handle. EMS_NOT_IMPLEMENTED if the function code passed to the manager is not defined. EMS_INTERNAL_ERROR if a malfunction in the memory manager software is detected. EMS_HARDWARE_ERROR if a malfunction in the expanded memory hardware is detected. EMS_INVALID_HANDLE if EMS couldn't find the EMM handle your program specified. Parameters: Handle - contains the EMM handle (integer). Pages - pointer to an integer value that will be set to the number of logical pages allocated to the specified EMM handle. This number never exceeds 2048 because the memory manager allows a maximum of 2048 pages (32M bytes) of expanded memory. Example: See EMS_Init SCL1 Version 3.1 - Reference Manual - Page 50 EMS_Init ----------------------------------------------------------------- EMS_Init ----------------------------------------------------------------- Purpose: Initialize the Expanded Memory Management functions. Determine if a valid Expanded Memory Manager (EMS driver) has been installed in your system. Prototype: int EMS_Init(void); Returns: Returns one of the following messages defined in header file SCL1EMS.H: EMS_OK if EMS has been initialized. EMS_NOT_IMPLEMENTED if EMS has not been implemented. Parameters: None Example: #include <memory.h> #include <dos.h> #include <scl1ems.h> /* Shows the use of EMS (Expanded memory functions */ void HandleReport(void); void Pause(void); void PrintError(unsigned int Error); char *TestStr[]={ "Data for Page 0", "Data for Page 1", "Data for Page 2", "Data for Page 3", }; typedef struct{ unsigned int ErrorCode; char *ErrorMess; }EMSERRORS; EMSERRORS emse[]= { EMS_NOT_AVAILABLE ,"EMS is not available", EMS_INTERNAL_ERROR ,"Internal EMM error", EMS_HARDWARE_ERROR ,"Hardware Error", EMS_MANAGER_BUSY ,"EMS Manager busy", EMS_INVALID_HANDLE ,"Invalid handle", SCL1 Version 3.1 - Reference Manual - Page 51 EMS_Init EMS_NOT_IMPLEMENTED ,"Function is not implemented", EMS_NO_MORE_HANDLE ,"No more handles available", EMS_SAVE_REST_ERROR ,"Save/restore error", EMS_LOG_GREATER_PH ,"Not enough physical pages", EMS_LOG_GREATER_AVA ,"Not enough available logical pages", EMS_ZERO_ALLOC ,"Allocation of 0 pages", EMS_INVALID_LOG ,"Invalid logical page number", EMS_INVALID_PH ,"Invalid physical page number", EMS_STATE_SAVE_FULL ,"Save Stack full", EMS_SAVE_ALREADY ,"Already saved", EMS_RESTORE_FAIL ,"Failure restoring", EMS_S_NOT_IMPLEMENTED ,"Subfunction number not implemented", EMS_SOURCE_OVERWRITTEN ,"Source overwritten", EMS_SIZE_ERROR ,"Size error", EMS_OVERLAP ,"Overlapping regions", EMS_OFFSET_ERROR ,"Offset error", EMS_TOO_BIG ,"Size too big", EMS_OVERLAP_ERROR ,"Overlapping error", EMS_UNDEFINED_TYPE ,"Undefined memory type", EMS_DUPLICATE ,"Duplicate handle name", EMS_WRAP_ERROR ,"Wrap error", }; EMSMove emove; char HandleName[9]="SCL1V30"; main() { char buffer[80]; int i,handle; unsigned int ppages,lpages; void far *p,far *s; void *t; printf("\n\nSCL1 Version 3.1 Expanded Memory (EMS) Test\n"); /* Initialize expanded memory manager */ if(EMS_Init() != EMS_OK) { /* no EMS available */ printf("No EMS available\n"); exit(-1); } SCL1 Version 3.1 - Reference Manual - Page 52 EMS_Init /* Get EMM version number */ EMS_Version(&i); memset(buffer,0,sizeof(buffer)); /* use predefined macros to get the major and minor version number add 0x30 to these values to convert to ASCII, store in buffer */ buffer[0]=EMS_MAJOR_VER(i) + 0x30; buffer[1]='.'; buffer[2]=EMS_MINOR_VER(i) + 0x30; /* print version number */ printf("EMS version: %s\n",buffer); /* get EMM status and print answer */ printf("EMS status: "); if((i=EMS_Status())==EMS_OK) printf("OK\n"); else PrintError(i); Pause(); /* get physical pages info */ printf("Physical pages report\n"); /* get total number of physical pages */ EMS_TotalPhPages(&ppages); printf("\tTotal physical pages: %i\n",ppages); /* get each physical page address */ for(i=0;i < ppages;++i) { EMS_PageAddress(i,&p); printf("\tPhysical page %i address %X:%X\n",i,FP_SEG(p), FP_OFF(p)); if(i > 0 && i % 21 == 0) Pause(); } Pause(); SCL1 Version 3.1 - Reference Manual - Page 53 EMS_Init /* get logical pages info */ printf("Logical pages report\n"); /* get total number of logical pages */ EMS_TotalLogPages(&lpages); printf("\tTotal logical pages: %i\n",lpages); /* get number of available logical pages */ EMS_AvailableLogPages(&lpages); printf("\tAvailable logical pages: %i\n",lpages); Pause(); printf("Allocation/mapping/reallocation Test\n"); if(lpages) { /* allocate all available memory */ if((i=EMS_Alloc(&handle,lpages))==EMS_OK) { printf("\tSuccesful allocation of %i pages\n",lpages); if(EMS_SetHandleName(handle,HandleName)==EMS_OK) { printf("\tEMS handle has been named %s\n", HandleName); if(EMS_GetNamedHandle(HandleName,&i)==EMS_OK) printf("\tHandle number is %i\n",i); } /* print memory handle info */ HandleReport(); for(i=0;i < lpages,i < 4;++i) { printf("\tMapping Logical Page %i to Physical Page %i\n",i,i); EMS_Map(handle,i,i); EMS_PageAddress(i,&p); printf("\tPhysical page %i segment: %X\n",i, FP_SEG(p)); printf("\tWriting to logical page %i\n",i); _fmemcpy(p,TestStr[i],sizeof(TestStr[i])); printf("\tCopying from expanded memory to conventional memory using EMS_Move\n"); SCL1 Version 3.1 - Reference Manual - Page 54 EMS_Init /* copy page 0 to our conventional memory buffer */ emove.bytes=sizeof(TestStr[i]); emove.stype=EMS_EXPANDED_MEM; emove.shandle=handle; emove.soffset=0; emove.sseg=0; emove.dtype=EMS_CONVENTIONAL_MEM; emove.dhandle=0; s=(void far *)buffer; emove.doffset=FP_OFF(s); emove.dseg=FP_SEG(s); EMS_Move(&emove); /* compare our buffer with page 0 */ if(_fmemcmp(p,(void far *)buffer,sizeof(TestStr[i])) ==0) printf("\tLogical page %i copied to conventional memory, compares OK\n",i); else printf("\tLogical page %i copied to conventional memory, error in compare\n",i); Pause(); } /* re-allocate to 1 page (16Kb) */ if((i=EMS_Realloc(handle,1))==EMS_OK) { printf("\tReallocated to 1 page\n"); /* print memory handle info */ HandleReport(); } /* free allocated memory */ EMS_Free(handle); } else printf("\tError allocating EMS %x\n",i); } } SCL1 Version 3.1 - Reference Manual - Page 55 EMS_Init void HandleReport(void) { EMSHandle p[255]; char buffer[9]; int i; /* get number of active handles */ memset(buffer,0,sizeof(buffer)); EMS_GetHandleCount(&i); printf("\tHandle report\n"); printf("\t\tActive handles: %i\n",i); /* print the number of memory pages associated with each handle */ if(EMS_GetAllHandlePages(p,&i)==EMS_OK) { while(i--) { EMS_GetHandleName(p[i].handle,buffer); printf("\t\tHandle %s %i, %i pages\n",buffer,p[i].handle, p[i].pages); } } } void Pause(void) { printf("-- more --"); GetKey(); printf("\r \n"); } void PrintError(unsigned int Error) { int i; for(i=0;i < sizeof(emse) /sizeof(EMSERRORS);++i) { if(emse[i].ErrorCode==Error) { printf("\t%s\n",emse[i].ErrorMess); return; } } printf("\tUnknown error #%X\n",Error); } SCL1 Version 3.1 - Reference Manual - Page 56 EMS_Map ----------------------------------------------------------------- EMS_Map ----------------------------------------------------------------- Purpose: Maps a logical page at a specific physical page anywhere in the mappable regions of memory. It can also unmap physical pages, making them inaccessible for reading or writing by setting its associated logical page to FFFFh. Prototype: int EMS_Map(int handle,int ppage,int lpage); Returns: Returns one of the following messages defined in header file SCL1EMS.H: EMS_OK if EMS has mapped the page. EMS_NOT_IMPLEMENTED if the function code passed to the memory manager is not defined. EMS_INTERNAL_ERROR if a malfunction in the memory manager software is detected. EMS_HARDWARE_ERROR if a problem in the expanded memory hardware is detected. EMS_INVALID_HANDLE if EMS could not find the handle specified. EMS_INVALID_LOG if the logical page is out of the range of logical pages which are allocated to the EMM handle or if a program attempts to map a logical page when no logical pages are allocated to the handle. EMS_INVALID_PH if the physical page number is out of the range of allowable physical pages. Parameters: handle - the EMM handle your program received from a call to the EMS_Alloc function (integer). ppage - the number of the physical page into which the logical page number is to be mapped. Physical pages are numbered zero-relative (integer). lpage - the number of the logical page to be mapped at the physical page within the page frame. Logical pages are numbered zero-relative (integer). Example: See EMS_Init SCL1 Version 3.1 - Reference Manual - Page 57 EMS_MapMultipleEMS ----------------------------------------------------------------- EMS_MapMultipleEMS ----------------------------------------------------------------- Purpose: Map (or unmap) logical pages into as many physical pages as the system supports. Prototype: int EMS_MapMultipleEMS(int handle,int entries, EMSMap *parameter); Returns: Returns one of the following messages defined in header file SCL1EMS.H: EMS_OK if EMS the logical pages have been mapped, or unmapped, at the specified physical pages. EMS_NOT_IMPLEMENTED if the function code passed to the manager is not defined. EMS_INTERNAL_ERROR if a malfunction in the memory manager software is detected. EMS_HARDWARE_ERROR if a malfunction in the expanded memory hardware is detected. EMS_INVALID_HANDLE if it couldn't find the specified EMM handle. EMS_S_NOT_IMPLEMENTED if an EMS subfunction is invalid. EMS_INVALID_LOG if one or more of the mapped pages is out of the range of logical pages which are allocated to the EMM handle or if a program attempts to map a logical page when no logical pages are allocated to the handle. EMS_INVALID_PH if one or more of the physical pages out of the range of mappable physical pages. Parameters: handle - the EMM handle your program received from a call to the EMS_Alloc function (integer). entries - contains the number of pages to map in the array (integer). parameter - pointer to an array of structures of the type EMSHandle as follows: SCL1 Version 3.1 - Reference Manual - Page 58 EMS_MapMultipleEMS - EMS_PageAdress typedef struct{ unsigned int logpage; The number of the logical page to be mapped from zero to (maximum number of logical pages allocated to the handle - 1). If the logical page number is set to FFFFh, the physical page is unmapped. unsigned int phpage; The number of the physical page at which the logical page is to be mapped from zero to (maximum number of physical pages supported in the system - 1). }EMSMap; Example: See EMS_Init ----------------------------------------------------------------- EMS_PageAdress ----------------------------------------------------------------- Purpose: Returns the address of a desired physical page number. Prototype: int EMS_PageAdress(int page,void far * far * pagept); Returns: Returns one of the following messages defined in header file SCL1EMS.H: EMS_OK if EMS has allocated the requested pages to the assigned EMM handle. EMS_NOT_IMPLEMENTED if the function code passed to the memory manager is not defined. EMS_INTERNAL_ERROR if a malfunction in the memory manager software is detected. EMS_HARDWARE_ERROR if a malfunction in the expanded memory hardware is detected. EMS_NO_MORE_HANDLE if all EMM handles are being used. EMS_LOG_GREATER_PH if there aren't enough expanded memory pages present in the system to satisfy your program's request. EMS_LOG_GREATER_AVA if there aren't enough unallocated pages to satisfy your program's request. SCL1 Version 3.1 - Reference Manual - Page 59 EMS_PageAdress - EMS_Realloc EMS_ZERO_ALLOC if your program attempted to allocate zero pages. Parameters: page - desired physical page number (integer). pagept - pointer to a pointer that will contain the address of the desired page number. Example: See EMS_Init ----------------------------------------------------------------- EMS_Realloc ----------------------------------------------------------------- Purpose: Allows an application program to increase or decrease (reallocate) the number of logical pages allocated to an EMM handle. Prototype: int EMS_Realloc(int handle,int pages); Returns: Returns one of the following messages defined in header file SCL1EMS.H: EMS_OK if EMS has returned the array. EMS_NOT_IMPLEMENTED if the function code passed to the manager is not defined. EMS_INTERNAL_ERROR if a malfunction in the memory manager software is detected. EMS_HARDWARE_ERROR if a malfunction in the expanded memory hardware is detected. Parameters: handle - the EMM handle your program received from a call to the EMS_Alloc function (integer). pages - contains the new size of the allocated memory block (unsigned integer). Example: See EMS_Init SCL1 Version 3.1 - Reference Manual - Page 60 EMS_RestorePageMap ----------------------------------------------------------------- EMS_RestorePageMap ----------------------------------------------------------------- Purpose: Restores the page mapping register contents on the expanded memory boards for a particular EMM handle. This function lets your program restore the contents of the mapping registers its EMM handle saved. Prototype: int EMS_RestorePageMap(int handle); Returns: Returns one of the following messages defined in header file SCL1EMS.H: EMS_OK if EMS has restored the state of the page mapping registers. EMS_NOT_IMPLEMENTED if the function code passed to the memory manager is not defined. EMS_INTERNAL_ERROR if a malfunction in the memory manager software is detected. EMS_HARDWARE_ERROR if a malfunction in the expanded memory hardware is detected. EMS_INVALID_HANDLE if the specified EMM handle cannot be found. EMS_RESTORE_FAIL if there is no page mapping register state in the save area for the specified EMM handle. Your program didn't save the contents of the page mapping hardware, so Restore Page can't restore it. Parameter: handle - the EMM handle your program received from a call to the EMS_Alloc function (integer). Example: See EMS_Init SCL1 Version 3.1 - Reference Manual - Page 61 EMS_SavePageMap ----------------------------------------------------------------- EMS_SavePageMap ----------------------------------------------------------------- Purpose: Saves the contents of the page mapping registers on all expanded memory boards in an internal save area. The function is typically used to save the memory mapping context of the EMM handle that was active when a software or hardware interrupt occurred. Prototype: int EMS_SavePageMap(int handle); Returns: Returns one of the following messages defined in header file SCL1EMS.H: EMS_OK if EMS has saved the state of the page mapping hardware. EMS_NOT_IMPLEMENTED if the function code passed to the memory manager is not defined. EMS_INTERNAL_ERROR if a malfunction in the memory manager software is detected. EMS_HARDWARE_ERROR if a malfunction in the expanded memory hardware is detected. EMS_INVALID_HANDLE if the specified EMM handle cannot be found. EMS_STATE_SAVE_FULL if there is no room in the save area to store the state of the page mapping registers. The state of the map registers has not been saved. EMS_SAVE_ALREADY if the save area already contains the page mapping register state for the EMM handle your program specified. Parameter: handle - the EMM handle your program received from a call to the EMS_Alloc function (integer). Example: See EMS_Init SCL1 Version 3.1 - Reference Manual - Page 62 EMS_SetHandleName ----------------------------------------------------------------- EMS_SetHandleName ----------------------------------------------------------------- Purpose: Assigns an eight character name to a handle. There is no restriction on the characters which may be used in the handle name. The full range of values may be assigned to each character in a name (that is, 00h through FFh). Prototype: int EMS_SetHandleName(int handle,char *name); Returns: Returns one of the following messages defined in header file SCL1EMS.H: EMS_OK if EMS has assigned the handle name. EMS_NOT_IMPLEMENTED if the function code passed to the manager is not defined. EMS_INTERNAL_ERROR if a malfunction in the memory manager software is detected. EMS_HARDWARE_ERROR if a malfunction in the expanded memory hardware is detected. EMS_INVALID_HANDLE if EMS couldn't find the EMM handle your program specified. EMS_S_NOT_IMPLEMENTED if an EMS subfunction is invalid. EMS_DUPLICATE if a handle with the specified name already exists. The specified handle was not assigned a name. Parameters: handle - contains the EMM handle (integer). name - pointer to an array which contains the name that is to be assigned to the handle. The handle name must be padded with nulls if the name is less than eight characters long. Example: See EMS_Init SCL1 Version 3.1 - Reference Manual - Page 63 EMS_Status ----------------------------------------------------------------- EMS_Status ----------------------------------------------------------------- Purpose: Returns a status code indicating whether the memory manager is present and the hardware is working correctly. Prototype: int EMS_Status(void); Returns: Returns one of the following messages defined in header file SCL1EMS.H: EMS_OK if EMS is present in the system, and the hardware is working correctly. EMS_NOT_IMPLEMENTED if EMS has not been implemented. EMS_INTERNAL_ERROR if a malfunction in the memory manager software is detected. EMS_HARDWARE_ERROR if a malfunction in the expanded memory hardware is detected. Parameters: None Example: See EMS_Init SCL1 Version 3.1 - Reference Manual - Page 64 EMS_TotalLogPages ----------------------------------------------------------------- EMS_TotalLogPages ----------------------------------------------------------------- Purpose: Returns the total number of expanded memory pages. Prototype: int EMS_TotalLogPages(unsigned int *npages); Returns: Returns one of the following messages defined in header file SCL1EMS.H: EMS_OK if EMS has returned the number of unallocated pages and the number of total pages in expanded memory. EMS_NOT_IMPLEMENTED if the function code passed to the manager is not defined. EMS_INTERNAL_ERROR if a malfunction in the memory manager software is detected. EMS_HARDWARE_ERROR if a malfunction in the expanded memory hardware is detected. Parameter: npages - pointer to an unsigned integer that will contain the number of expanded memory pages that are available. Example: See EMS_Init SCL1 Version 3.1 - Reference Manual - Page 65 EMS_Version ----------------------------------------------------------------- EMS_Version ----------------------------------------------------------------- Purpose: Returns the version number of the memory manager software. Prototype: int EMS_Version(unsigned int *version); Returns: Returns one of the following messages defined in header file SCL1EMS.H: EMS_OK if EMS has been initialized and the hardware is working correctly. EMS_NOT_IMPLEMENTED if the function code passed to the memory manager is not defined. EMS_INTERNAL_ERROR if a malfunction in the memory manager software is detected. EMS_HARDWARE_ERROR if a malfunction in the expanded memory hardware is detected. Parameter: version - pointer that will contain the memory manager's version number in binary coded decimal (BCD) format. The upper four bits contain the integer digit of the version number. The lower four bits contain the fractional digit of version number (unsigned integer). Two macros EMS_MAJOR_VER(i) and EMS_MINOR_VER(i) have been defined int SCL1EMS.H. These macros extract the EMS version number from the variable version. To get the most significant part (MAJOR) of the version number use the following relation: Major=EMS_MAJOR_VER(i); The get the least significant part (MINOR) of the version number use the following relation: Minor=EMS_MINOR_VER(i); The EMS driver version number will be: Version Number = Major.Minor Example: See EMS_Init SCL1 Version 3.1 - Reference Manual - Page 66 ErrorBox ----------------------------------------------------------------- ErrorBox ----------------------------------------------------------------- Purpose: Displays a box, centered in the screen, with an error message. Standard error messages have been defined. You can add your own error messages or modify the standard messages with the InitUserError function and your own prompts with the EB_SetUserLang function. To define the color attributes and a shadow effect use ErrorShadowOff, ErrorShadowOn and SetErrorBoxColor. Prototype: 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 Example: #include <scl1.h> struct ErrorMess em[]={ 256,"Please type either Y for YES\nor N for NO", 0}; main() { int Key; SCL1 Version 3.1 - Reference Manual - Page 67 ErrorBox - ErrorShadowOff - ErrorShadowOn 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, InitUserError and EB_SetUserLang. ----------------------------------------------------------------- ErrorShadowOff, ErrorShadowOn ----------------------------------------------------------------- Purpose: Enables or disables a shadow effect when using the ErrorBox function. Subsequent calls to ErrorBox will be displayed with (or without) a shadow effect. Prototype: void ErrorShadowOff(void); void ErrorShadowOn(void); Returns: Nothing. Parameters: None. Example: #include <scl1.h> struct ErrorMess em[]={ 1000,"ErrorBox without shadow", 1001,"ErrorBox with shadow", 0}; main() { InitUserError(em); SetShadowColor(8); ErrorBox(1000); ErrorShadowOn(); ErrorBox(1001); ErrorShadowOff(); ErrorBox(1000); } See ErrorBox, InitUserError and SetErrorBoxColor. SCL1 Version 3.1 - Reference Manual - Page 68 FB_SetUserLang - FB3_SetUserLang - WF_SetUserLang ----------------------------------------------------------------- FB_SetUserLang, FB3_SetUserLang, WF_SetUserLang ----------------------------------------------------------------- Purpose: Lets you modify the default prompts of the FileBox and FileBox2 (FB_SetUserLang), FileBox3 (FB3_SetUserLang) or WFileBox (WF_SetUserLang) functions. With this function you can customize the default "Load" "Cancel" and "Dir" prompts. This can useful when writing programs in languages other than english. Prototype: void FB_SetUserLang(char **prompt,int offset1, int offset2); void FB3_SetUserLang(char **prompt,int offset1, int offset2); void FB_SetUserLang(char **prompt,int offset1, int offset2); Returns: Nothing. Parameters: prompt - pointer to a null terminated array of char pointers that holds the modified prompts. offset1 - distance from the right margin (left margin for WF_SetUserLang) of the box where the first mouse button ("LOAD") will be displayed. offset2 - distance from the right margin (left margin for WF_SetUserLang) of the box where the second mouse button ("CANCEL") will be displayed. Example: /* this function call sets the FileBox prompts to Spanish */ char *myprompts[]={ "< ACEPTAR >", "< CANCELAR >", ">>>>", 0, }; FB_SetUserLang(myprompts,3,3); SCL1 Version 3.1 - Reference Manual - Page 69 FieldCheck ----------------------------------------------------------------- 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 whether the cursor should move to the next or 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 fields are active, pressing ENTER moves control to the next field. When ScrollWindow or ListWindow are active, pressing ENTER will select 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 of the events mentioned above. Prototype: int FieldCheck(FData2 *p); Returns: The return value is a message. Please refer to the Fields2 function for details. Parameters: The required parameter is a pointer to the FData2 structure of the field to be checked. Example: See Fields2 SCL1 Version 3.1 - Reference Manual - Page 70 Fields ----------------------------------------------------------------- Fields ----------------------------------------------------------------- Purpose: This function permits you to make data entry screens. The fields can accept keyboard input and permit editing. You can move across the fields using the TAB, SHIFTTAB keys or your mouse. An exit key is defined when calling the function. You can define a data validation and a help function associated with each field. When you reach each field's end, the cursor jumps to the next field, thus special field types (such as date fields) can be defined as separate fields make them look as one. Prototype: int Fields(int NColor, int RColor, int NFields, struct InputFields *ifld, unsigned int ExitKey, unsigned int HelpKey); Returns: Returns "1" if a key defined as an exit key is pressed and "-1" if the ESC key is pressed. Parameters: The fields information must entered as an array of structures as follows: struct InputFields{ int PromptLine; Row position to start the prompt display. int PromptCol; Column to start the prompt display. char *Prompt; Char pointer to the prompt to be displayed. int FieldLine; Row to start the field display. int FieldCol; Column to start the field display. char *FieldBuffer; Pointer to the buffer to be used to store the field contents. int MaxChar; Length of the input field. int CharType; Mask of valid characters as described in function CheckChar. int (* Helpf)(struct InputFields *p); pointer to a help function. This function receives a pointer to the fields structure and must be user supplied. SCL1 Version 3.1 - Reference Manual - Page 71 Fields int (* CheckF)(struct InputFields *p); pointer to a field validation function. This function receives a pointer to the fields structure and must be user supplied. It must return a value of "0" if the field fails the test or a value of "1" to accept the entry. }; The parameters required are: NColor - color attributes for the prompt display (int). 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 a 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]; struct InputFields data[]={ 4,3,"Name:",4,11,buffer1,28,CC_ANY,helpf,test, 6,3,"Address:",6,11,buffer2,28,CC_ANY,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, SCL1 Version 3.1 - Reference Manual - Page 72 Fields 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 No:",12,60,buffer10,10,CC_DIGIT,helpf, test}; main() { Cls(WHITE_BLACK,CLS_ALL); Fields(WHITE_BLACK,BLACK_WHITE,10,data,F10,F1); } helpf(struct InputFields *p) /* This function will be called every time the key defined for help is pressed. It is possible to design a context sensitive help facility using this feature */ { PushCursor(); CursorOff(); MessageOn(BLACK_WHITE,"This function will\ndisplay your help screens."); WaitTime(200); MessageOff(); PopCursor(); } test(struct InputFields *p) /* This function is called every time you exit a field. It can make field validation */ { PushCursor(); MessageOn(BLACK_WHITE,"This function can perform data validation\neach time the cursor moves out of the field."); WaitTime(300); MessageOff(); PopCursor(); return(1); } NOTE: The Fields2 function provides a more flexible way to perform the same task. SCL1 Version 3.1 - Reference Manual - Page 73 Fields2 ----------------------------------------------------------------- Fields2 ----------------------------------------------------------------- Purpose: This function lets you integrate various dialog type functions to design very powerful data entry and dialog screens. It is similar to Fields but more flexible. Every field can have its own field check function which you can create to provide help and data validation. The screens can contain any of the following fields: Line Editor - to enter and edit text and numeric data. Scroll Window - to display a window with a list of items that permits tagging or selecting items. Mouse Button - a single prompt that permits either to ignore or activate it. Tag Item - a field that permits to tag one or various options. Select - a field with multiple items for selection. List Window - similar to the Scroll Window but permits multiple items in each line. Calendar - to display a calendar of a given date and permit the user to modify the date. User Defined - a field defined by the user. Prototype: 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. Returns a pointer to the FData2 structure. Parameters: Dialog type functions receive messages and structures as parameters. The field information is given as an array of structures type FData1 as follows, one element for each field: FData1 structure: typedef struct{ int FieldType; The type of function for each field defined in SCL1.H as follows: SCL1 Version 3.1 - Reference Manual - Page 74 Fields2 LINE_EDITOR, SCROLL_WINDOW, MOUSE_BUTTON, TAG_ITEM SELECT, LIST_WINDOW, CALENDAR or USER_DEFINED void *Structure1; Pointer to a structure that contains all the information required for the field. void *Structure2; Pointer to a second structure that contains the field information. Use "0" if the field type does not require it. int (* CheckF)(); Pointer to a function, called every time an event occurs, that will be responsible for the program flow. It will constantly receive messages from Fields2 and return messages to Fields2 telling it what should be done. This allows complete control of the behavior of Fields2, as well as to perform complex data validation, context-sensitive help, etc. SCL1 includes a generic CheckF called FieldCheck, you should use this function even if you create your own CheckF. Refer to FieldCheck for more information. }FData1; Fields2 needs a secondary structure type FData2. It is used for communication between Fields2, CheckF and the calling program. Each time an event occurs CheckF is called. By reading the FData2 Message element, CheckF knows what has just happened. For example, the user may 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 typed a character. CheckF is responsible of telling Fields2 what should be done. Type FData2 structure: typedef struct{ int Message; Message returned by the active field. unsigned int EventInfo; Information about the keys that have been pressed. FData1 *Structure; Pointer to the FData1 structure. int ActiveField; Keeps a record of the current field, starting with "0" for the first field. Used internally by the function. SCL1 Version 3.1 - Reference Manual - Page 75 Fields2 int FieldsNumber; Holds the number of fields, used internally by the function. }FData2; Type structure FData3: typedef struct{ int EventInfo; Information about the last illegal or exit key that was pressed. int (* UserField)(); Pointer to the function that will handle user defined fieldtype. }FData3; NOTE: The information stored in structure type FData3 is used to define the parameters for user defined fields, please refer to the sample user defined function after the Fields2 example. Messages: The messages that can be sent to the Fields2 function are: F_INIT - initialize the FData2 structure. F_DRAW - draw the Fields2 screen. F_ACTIVE - edit the Fields2 information. F_DRAW_NR - draw the Fields2 display and do not reset the field values. With the F_DRAW message, Fields2 resets all the fields to their starting position. F_COLORS - dialog functions get the colors from their structures. If you have initialized these structures as static data you can change the colors by sending 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 and the second is the Reversed Color. F_ALLOC - after this message is sent, when Fields2 finds a LineEditor type field, it will automatically allocate memory for the buffer. F_FREE - when this message is sent Fields2 will free all buffers allocated for LineEditor type fields. It is recommended that either allocate all buffers using F_ALLOC or manually but not both. When this message is sent it will clear all buffers, so be careful. SCL1 Version 3.1 - Reference Manual - Page 76 Fields2 When the CheckF is called, after determining what should be done, it can send one the following messages back to Fields2: F_MOUSE_EVENT - When the mouse is clicked outside the active field FieldCheck will receive a LE_MOUSE_EVENT (SW_ or LW_ etc.) and FieldCheck should return a F_MOUSE_EVENT message to Fields2. Fields2 will then give control to the field (if any) that can handle the mouse event. F_POSITION_STAY - instructs Fields2 not to move to other field. It is useful when 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 - 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. F_CHECK_ALL - when a CheckF senses an exit condition, it sends this message to Fields2 who will call any CheckF defined 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 it will behave as an F_EXIT message. F_FIELDSTART - when the cursor is located in one valid field this message will be sent to the FieldCheck function. F_START - This message is sent to the FieldCheck function (in the FData2 Message element) when Fields2 first receives the F_ACTIVE message. You can use this message to initialize or modify any condition before the user gets control. Due to the function integrating purpose of Fields2, it does not return messages. SCL1 Version 3.1 - Reference Manual - Page 77 Fields2 Example: #include <string.h> #include <scl1.h> #include <scl1keys.h> #include <scl1clor.h> /* Shows the use of the Fields2 and FieldCheck functions and how to create an user defined field check function. The data entry field has a Select type field, one LineEditor and two mouse buttons. The field check function will: 1) Check for F1 key to display context sensitive help. 2) Check if user has selected YES or NO. The LineEditor field color is grayed in the case of NO. 3) Keep the cursor off the LineEditor field if the user has selected NO and the LineEditor field is grayed out. 4) Check before exit if cancel is not selected and YES has been selected if the user has fill out the LineEditor field. */ int OurFieldCheck(FData2 *fd2); /* our CheckF prototype */ int Color1=WHITE_BLUE; /* Colors are initialized */ int Color2=BLACK_CYAN; /* for a color monitor */ int Color3=BROWN_BLACK+HIGHLIGHT; /* 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}; /* Our second field will be a LineEditor type. This structure defines the LineEditor configuration */ LEData led={23,13,16,"Backup Directory:",112,13,34,30,30, CC_PATH+CC_CAPITALIZE, 0,0,0,0,0,0,2,1,0,0,0,0,0,0,0}; SCL1 Version 3.1 - Reference Manual - Page 78 Fields2 /* The next two fields will be of the MouseButton type. */ 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}; FData1 fd1[]={ /* This is the FData1 structure: */ SELECT,sd1,&sd2,OurFieldCheck, LINE_EDITOR,&led,0,OurFieldCheck, MOUSE_BUTTON,&mb1,0,OurFieldCheck, MOUSE_BUTTON,&mb2,0,OurFieldCheck, 0}; char F1Text[]=" Press F1 for Help "; main() { FData2 fd2; /* Fields2 secondary structure */ if(Video()==MONO) /* Verify the type of display and change */ { /* colors if necessary */ Color1=WHITE_BLACK; Color2=BLACK_WHITE; Color3=BLACK_WHITE+HIGHLIGHT; } /* Clear the screen and draw a box */ Cls(Color1,10,13,16,66); Box(Color1,0,10,13,16,66); WriteScreen(Color1,16,Center(F1Text),F1Text); /* Call Fields2 with a F_INIT message */ Fields2(F_INIT,fd1,&fd2); /* allocate buffer for LineEditor field */ Fields2(F_ALLOC,fd1,&fd2); /* Tell Fields2 to modify colors to new values */ Fields2(F_COLORS,fd1,&fd2,Color1,Color2); /* Draw fields */ Fields2(F_DRAW,fd1,&fd2); InitMouse(IM_SHOW); SCL1 Version 3.1 - Reference Manual - Page 79 Fields2 /* 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); /* 1) We will watch the F1 help key. It will be reported by Fields2 with an ILLEGAL_KEY message in the FData2 EventInfo structure element.*/ if(fd2->Message == LE_ILLEGAL_KEY && fd2->EventInfo==F1) { /* display help, fd2->ActiveField = active field number */ Help(fd2->ActiveField); /* return POSITION_STAY message so that the cursor is not moved to another field */ Mess=F_POSITION_STAY; } /* 2) Check if the Select field is active and if a S_NEW_POSITION message, was send by Select. This message is received each time the user changes his selection. We'll check current position to validate or invalidate the LineEditor field */ else if(fd2->ActiveField==0 && fd2->Message==S_NEW_POSITION) { if(sd2.Position==0) /* YES selected */ SCL1 Version 3.1 - Reference Manual - Page 80 Fields2 { led.PColor=Color1; led.FColor=Color2; /* normal colors */ } else /* NO selected, use gray color */ { led.PColor=BLACK_BLUE + HIGHLIGHT; led.FColor=BLACK_BLACK + HIGHLIGHT; } LineEditor(LE_DRAW,&led); /* redraw LineEditor */ } /* 3) The FIELDSTART message is send each time a new field receives control. We'll check this message and if the LineEditor field is active we'll check its color. If it is set to gray color it means that the user has selected not to create backup files. In this case we'll move to the next or previous field. By checking fd2->EventInfo we'll know if the user had previously pressed TAB (for the next field) or SHIFT+TAB */ else if(fd2->ActiveField==1 && fd2->Message==F_FIELDSTART) { if(led.FColor==BLACK_BLACK + HIGHLIGHT) { if(fd2->EventInfo==TAB) fd2->ActiveField=2; /* next field */ else fd2->ActiveField=0; /* previous field */ Mess=F_SET_POSITION; } } /* 4) When the user wants to exit we'll check if a string has been entered in the LineEditor field if Select is set to YES and the OK mouse button was selected. We know we are about to exit fields when FieldCheck returns and F_EXIT message. We'll also check if the key that was used to exit was ESCAPE or the CANCEL button was selected, in these cases the user has selected to cancel the operation. */ else if(Mess==F_EXIT && fd2->EventInfo != ESC && fd2->ActiveField != 3) { SCL1 Version 3.1 - Reference Manual - Page 81 Fields2 /* if Select is in YES position and no directory has been entered */ if(sd2.Position==0 && strlen(led.Buffer)==0) { /* display error, change message to POSITION_STAY and move the cursor to the LineEditor field */ MessageOn(Color3,"Directory must be entered!"); Mess=F_POSITION_STAY; fd2->ActiveField=1; WaitKeyMouse(); MessageOff(); } } /* Mess holds the message Fields2 will receive, a POSITION_STAY message or the message returned by FieldCheck */ return(Mess); } char AllHelp[]=" TAB-next SHIFT TAB-previous "; Help(int field) { /* save cursor status and turn it off */ PushCursor(); CursorOff(); /* field tells us the field number that is active, we will use it to display context sensitive help */ switch(field) { case 0: /* first field */ MessageOn(Color3,"Use arrow keys to select if you\nwant to create backup files."); break; case 1: /* second field */ MessageOn(Color3,"Type Backup files directory."); break; SCL1 Version 3.1 - Reference Manual - Page 82 Fields2 case 2: /* third field */ MessageOn(Color3,"Press ENTER to validate\nyour selection."); break; case 3: /* fourth field */ MessageOn(Color3,"Press ENTER or ESC to\ncancel your selection."); break; } WriteScreen(Color3,12,Center(AllHelp),AllHelp); /* wait for mouse or keystroke, remove message, restore cursor */ WaitKeyMouse(); MessageOff(); PopCursor(); } /**************************************************************** This example shows how to create an user defined field type to use with the Fields2 function. We will create a field that displays one of several predefined strings. The user can select one by using the UP and DOWN arrow keys or by clicking the mouse after pointing at any of the two small arrows. To create an user defined field we need to create the function that will handle the new field type. This function must be written with the following requirements: 1) The function must be capable of receiving and handling the following messages: Message Action RESET - Reset all internal variables to start-up conditions. DRAW - Draw the field to the screen. ACTIVE - Get user input. CHECK_MOUSE - Check if a mouse event has occurred inside the field area. SCL1 Version 3.1 - Reference Manual - Page 83 Fields2 2) The function must return the following messages to Fields2: Message Action OK - Action requested was successfully performed. EXIT_KEY - A key defined as an exit key was pressed. ILLEGAL_KEY - An unknown key was pressed. MOUSE_EVENT - A mouse event not related to this function has occurred. MY_MOUSE - A CHECK_MOUSE message is answered with this message if the mouse event is related to this function. Fields will give control to this function when a MY_MOUSE event is returned. NEW_POSITION - the user has moved to a new position or selected a new element. (This one is not required but it is highly recommended). 3) All local data (color, position, etc.) must be stored in a structure. A pointer to this structure will be passed as a parameter whenever the function is called. Look at any SCL1 dialog function for an example. The use of a structure to hold local data makes possible for a single LineEditor structure to handle all LineEditor fields in a data-entry screen. 4) The following parameters are passed each time the function is called: Message (int) any of the messages described above. st (void *) pointer to the field related structure. fd3 (FData3 *) pointer to a FData3 structure that has the following format: typedef struct{ int EventInfo; int (* cdecl UserField)(); }FData3; 5) When called the function must: SCL1 Version 3.1 - Reference Manual - Page 84 Fields2 a) Service the message received. b) If an illegal or exit key is detected it should copy the key's SCAN/ASCII code to the EventInfo element of the FData3 struct. c) Return the correct message. Before calling Fields2 you must properly initialize the user defined and the FData3 structure. In the case of FData3 only the UserField element needs to be initialized (points to the function that will handle the user defined field type). ****************************************************************/ #include <scl1.h> #include <scl1keys.h> /* function prototype of our new field handler */ int SelectString(int Message,void *st,FData3 *fd3); /* new field data */ char *MyText[]={ "111111111111111111", "222222222222222222", "333333333333333333", 0, }; typedef struct{ /* our new field structure */ int Color; int Row; int Col; int Position; int Items; int Length; char **Text; }SSData; /* initialize our field structure */ SSData ssd={7,7,13,0,3,0,MyText}; /* a mouse button structure */ MBData mb={7,112,9,13,9,18,9,13,"< OK >",0,0,0,0}; SCL1 Version 3.1 - Reference Manual - Page 85 Fields2 /* It is very important to initialize our FData3 structure so that the UserField element points to the function that handles the new field type */ FData3 ssfd3={0,SelectString}; /* FData1 struct */ FData1 fd1[]={ /* First field is our used defined field, the SSData pointer is used as Structure1 element and the FData3 pointer as Structure2 element. We will use SCL1's default FieldCheck function */ USER_DEFINED,&ssd,&ssfd3,FieldCheck, MOUSE_BUTTON,&mb,0,FieldCheck, 0}; main() { FData2 fd2; Cls(7,CLS_ALL); /* Clear screen */ InitMouse(IM_SHOW); /* initialize mouse */ Fields2(F_INIT,fd1,&fd2); /* init fields */ Fields2(F_DRAW,fd1,&fd2); /* draw */ Fields2(F_ACTIVE,fd1,&fd2); /* give control */ } /* our new field type. Here we'll send received messages for processing */ int SelectString(int Message,void *st,FData3 *fd3) { SSData *ssd; ssd=(SSData *)st; /* You could define any messages for your field, but the value assigned to each message must equal those assigned to regular dialog functions. In this example we will use LineEditor messages */ switch(Message) { case LE_DRAW: DrawUF(ssd); return(LE_OK); SCL1 Version 3.1 - Reference Manual - Page 86 Fields2 case LE_ACTIVE: return(ActiveUF(ssd,fd3)); case LE_CHECK_MOUSE: return(CheckUFMouse(ssd,fd3)); case LE_RESET: ssd->Position=0; /* reset position to 0 */ return(LE_OK); } return(LE_OK); } /* Draws our field to the screen and initializes several elements of our structure */ int DrawUF(SSData *ssd) { int i=0,j,maxlength=0; while(ssd->Text[i] != 0) /* count the number of items */ { j=strlen(ssd->Text[i]); /* save the largest element size */ if(j > maxlength) maxlength=j; ++i; } ssd->Items=i; /* save in struct */ ssd->Length=maxlength; /* write string */ WriteScreenLen(ssd->Color,ssd->Row,ssd->Col+2,maxlength,ssd->Text [ssd->Position]); /* draw up and down arrows */ WriteChar(ssd->Color,ssd->Row,ssd->Col,1,24); WriteChar(ssd->Color,ssd->Row,ssd->Col+maxlength+3,1,25); } /* This functions is called when our field is active */ ActiveUF(SSData *ssd,FData3 *fd3) { unsigned int key; SetCurPos(ssd->Row,ssd->Col+2); /* position cursor */ do { if(MSE_LPress) /* mouse event? */ { SCL1 Version 3.1 - Reference Manual - Page 87 Fields2 if(CheckUFMouse(ssd)==LE_MY_MOUSE) /* our mouse? */ { /* clicked at the up arrow key */ if(MSE_LpX==ssd->Col) { WaitTime(25); goto UpKey; } /* clicked at the down arrow key */ else if(MSE_LpX==ssd->Col+ssd->Length+3) { WaitTime(25); goto DownKey; } } else /* clicked outside our area, return a MOUSE_EVENT message */ return(LE_MOUSE_EVENT); } if(KeyReady()) /* check keystrokes */ { key=GetKey(); switch(key) { case UP: UpKey: if(ssd->Position > 0) --ssd->Position; /* change position */ else ssd->Position=ssd->Items-1; DrawUF(ssd); /* update screen */ return(LE_NEW_POSITION); case DOWN: DownKey: if(ssd->Position + 1 < ssd->Items) ++ssd->Position; /* change position */ else ssd->Position=0; DrawUF(ssd); /* update screen */ return(LE_NEW_POSITION); case TAB: case SHIFTTAB: /* handle exit keys */ SCL1 Version 3.1 - Reference Manual - Page 88 Fields2 case ESC: fd3->EventInfo=key; /* save key value */ return(LE_EXIT_KEY); default: /* handle unknown keys */ fd3->EventInfo=key; /* save key value */ return(LE_ILLEGAL_KEY); } } }while(1); } /* This function checks if the mouse has been clicked in our area */ CheckUFMouse(SSData *ssd) { if(MSE_LpY==ssd->Row && MSE_LpX >= ssd->Col && MSE_LpX <= ssd->Col+ssd->Length+3) /* return MY_MOUSE if YES */ return(LE_MY_MOUSE); else return(LE_MOUSE_EVENT); } SCL1 Version 3.1 - Reference Manual - Page 89 FileBox ----------------------------------------------------------------- FileBox ----------------------------------------------------------------- Purpose: Displays a box with the directory information for loading or selecting files with the keyboard or mouse. Fills a buffer with the selected file/path. You can change the MouseButton and prompt text with the FB_SetUserLang function. Prototype: int FileBox(int NColor, int RColor,char *Buffer); Returns: Returns "-1" if the operation is canceled by the user by pressing ESC or selecting the cancel option, or "0" if there are no problems. Parameters: NColor - color attributes for normal color display (int). RColor - color attributes for reverse color display (int). Buffer - char pointer to the buffer that will 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 it. This buffer must be of size FB_BUF_SIZE as defined in SCL1.H. Example: #include <scl1.h> #include <scl1clor.h> int Color1=BLACK_WHITE; int Color2=WHITE_BLACK; char FileBuf[FB_BUF_SIZE]; /* 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, FileBox3 and WfileBox. SCL1 Version 3.1 - Reference Manual - Page 90 FileBox2 - FileBox3 - WFileBox ----------------------------------------------------------------- FileBox2, FileBox3, WFileBox ----------------------------------------------------------------- Purpose: FileBox2 displays a box with for selecting files using the keyboard or mouse. Fills a buffer with the selected file/path. Displays the action MouseButtons at the right of the box. You can change the MouseButton and prompt text with the FB_SetUserLang function. FileBox3 can also display the file's size, date, time and attributes. Files can be sorted by name, extension, size, date, time or attribute. You can change the prompts and MouseButton text using the FB3_SetUserLang function. WFileBox is similar to FileBox2 but uses a full screen. You can use WF_SetUserLang to change the Mouse Button prompts. Prototype: int FileBox2(int Message, FBData *p) int FileBox3(int Message, FB3Data *fb3) 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. Returns the messages described in the Messages section. Parameters: The file box information is given in a structure type FBData (for FileBox2 and WFileBox) or FB3Data (for FileBox3) as follows: Structure type FBData; (Used with FileBox2 and WFileBox) typedef struct{ int NColor; Normal color for the file box display. int RColor; Reversed color for the file box display. int UpperRow; Upper row position for the file box. int LeftCol; Left column position for the file box. int LowerRow; Lower row position for the file box. int RightCol; Right column position for the file box. SCL1 Version 3.1 - Reference Manual - Page 91 FileBox2 - FileBox3 - WFileBox char *Filename; Char pointer to the buffer that will hold the selected filename. The search string is placed in the buffer before calling the function. If an empty buffer is used, the function will place the default path and the "*.*" search string in the buffer. It must be of size FB_BUF_SIZE as defined in SCL1.H. int Attrib; File attributes as defined by the DOS. Refer to Appendix "A" for more details. }FBData; Structure type FB3Data; typedef struct{ int NColor; See description for FBData structure above. int RColor; " " int UpperRow; " " int LeftCol; " " int LowerRow; " " int RightCol; " " char *Filename; " " int Attrib; " " unsigned int Display; Variable used to specify what to show in the FileBox display. The following constants can be used in this specification: FB_NAME - show name. FB_SIZE - show size. FB_DATE - show date. FB_TIME - show time. FB_ATTRIB - show attributes. FB_DMY - show date using the Day- Month-Year format. FB_YMD - show date using the Year- Month-Day format. They can be concatenated (added) to specify various options,as in: FB_NAME + FB_SIZE + FB_DATE + FB_TIME + FB_ATTRIB unsigned int SortType; Variable used to define the desired sorting order of the files. The following constants can used in this specification: SCL1 Version 3.1 - Reference Manual - Page 92 FileBox2 - FileBox3 - WFileBox FB_NAME - sort by name FB_EXT - sort by extension FB_DATE - sort by date FB_ATTRIB - sort by attribute The following constants can be used to specify the sorting action: FB_REVERSE - sort in reverse order FB_DIR_FIRST - place the directories before the files. int FileNumber; Number of files found. int DirNumber; Number of directories found. }FB3Data; Messages: The following messages can be sent to FileBox2, FileBox3 and WFileBox: FB_INIT - initialize the FBData or FB3Data structure to NULL and set the following default values: NColor - set to white characters in a black background or the normal color set by SetDialogColors. RColor - set to black characters in a white background or the reversed color set by SetDialogColors. UpperRow, LeftCol, LowerRow and RightCol - set to display the FileBox centered in the screen. Attrib - files and sub-directories. For FB3Data only; Display - set to show the file name, size, date, time and attributes. The date is displayed in the Month-Day-Year format. SortType - set to sort the files by name. FB_DRAW - draw the FileBox to the screen. FB_ACTIVE - browse through the displayed filenames and permit a selection or to cancel the operation using the cursor movement keys as follows: SCL1 Version 3.1 - Reference Manual - Page 93 FileBox2 - FileBox3 - WFileBox Key Action Up Arrow one item up. Down Arrow one item down. END end of file list. HOME beginning of list. Page Up one screen up. Page Down one screen down. FB_RESET - when this message is sent the filebox variables are reset to the default value. The following messages can be returned by FileBox2, FileBox3 and WFileBox: FB_OK - the action requested has been performed and a file has been selected. FB_CANCEL - the operation has been canceled. For FileBox3 only; FB_NO_MEM - there is not enough memory left to perform the requested action. FB_ILLEGAL_OP - you have specified an illegal option. Example: #include <scl1.h> #include <scl1clor.H> /* Shows the use of filebox functions */ main() { char Buffer[FB_BUF_SIZE]; FBData fb2; FB3Data fb3; FBData fbw; memset(Buffer,0,sizeof(Buffer)); InitMouse(IM_SHOW); FileBox2(FB_INIT,&fb2); /* initialize the FBData structure */ WFileBox(FB_INIT,&fbw); /* initialize the FBData structure */ FileBox3(FB_INIT,&fb3); /* initialize the FB3Data structure */ SCL1 Version 3.1 - Reference Manual - Page 94 FileBox2 - FileBox3 - WFileBox fb2.NColor=fb3.NColor=fbw.NColor=WHITE_BLACK;/* change display colors */ fb2.RColor=fb3.RColor=fbw.RColor= BLACK_WHITE; fb2.Filename=fb3.Filename=fbw.Filename=Buffer; /* buffer to hold dir info */ /* set files attributes */ fb2.Attrib=fb3.Attrib=fbw.Attrib=F_READ_ONLY+F_HIDDEN+F_SYSTEM+ F_DIRECTORY; FileBox2(FB_DRAW,&fb2); /* display FileBox */ FileBox2(FB_ACTIVE,&fb2); /* let user make a selection */ /* sort by name and place directories first in the list */ fb3.SortType=FB_NAME+FB_DIR_FIRST; FileBox3(FB_DRAW,&fb3); /* display FileBox */ FileBox3(FB_ACTIVE,&fb3); /* let user make a selection */ WFileBox(FB_DRAW,&fbw); /* display Wide FileBox */ WFileBox(FB_ACTIVE,&fbw); /* let user make a selection */ } SCL1 Version 3.1 - Reference Manual - Page 95 File2Buf - HFile2Buf ----------------------------------------------------------------- File2Buf, HFile2Buf ----------------------------------------------------------------- Purpose: Reads a file into a buffer. With HFile2Buf the file size can be larger than 64K, using the compact and large models. HFile2Buf's prototype is declared in SCL1HUGE.H Prototype: int File2Buf(char* Filename, char* Buffer, unsigned int* MaxSize); int HFile2Buf(char *Filename,char huge *Buffer, unsigned long *MaxSize); Returns: Returns "0" when no errors occur. When errors occur it returns "-1" to indicate a critical DOS error, "255" to indicate that the file is larger than the size specified with MaxSize, or 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 pointer for File2Buf and huge file pointer for Hfile2Buf). MaxSize - number of bytes to read (unsigned integer for File2Buf and unsigned long for Hfile2Buf). Example: See Buf2Disk See also Buf2Disk, HBuf2Disk and TrapInt24. SCL1 Version 3.1 - Reference Manual - Page 96 FillBlock ----------------------------------------------------------------- FillBlock ----------------------------------------------------------------- Purpose: Fills a screen area, defined with the parameters passed to the function, with a given character. Prototype: 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 position of the display area (integer). LeftCol - left column position of the display area (integer). LowerRow - lower row position of the display area (integer). RightCol - right column position of the display area (integer). Character - character to be used for filling the screen area. This can be any valid character (integer). 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. */ } SCL1 Version 3.1 - Reference Manual - Page 97 FindFirst - FindNext ----------------------------------------------------------------- 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. Prototype: int FindFirst(char *SearchString,struct FileData *Buffer, int SearchAtr); int FindNext(void); Returns: The DOS error code or "0" if no 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]; Is an area reserved by DOS for subsequent calls to FindNext. char 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 struct FILETIME 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; Value from "0" to "59". unsigned int minutes:6; Value from "0" to "59". unsigned int hours:5; Value from "0" to "24". }; SCL1 Version 3.1 - Reference Manual - Page 98 FindFirst - FindNext struct FILEDATE 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; Value from "1" to "31". unsigned int month:4; Value from "1" to "12". unsigned int year:7; value from "0" to "119", to get the real year add "80" to this value. }; long size; File's size in bytes. char name[13]; File's name. }; SearchAtr - is the DOS file attribute of eligible files (files that will be reported). The following attribute constants have been defined in SCL1.H: F_ARCHIVE only archive files. F_DIRECTORY archive and directories. F_READ_ONLY archive and read-only files. F_HIDDEN archive and hidden files. F_SYSTEM archive and system files. 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. The DTA must be declared as static data. Example: #include <scl1.h> /* Shows the use of FindFirst/Next to get a directory list */ #define NO_MORE_FILES 18 static void printinfo(struct FileData *fd); struct FileData fd; /* file info will be stored here */ main() { int RetVal; SCL1 Version 3.1 - Reference Manual - Page 99 FindFirst - FindNext 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); /* 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); SCL1 Version 3.1 - Reference Manual - Page 100 GetCharSet - GetCharSetAddress ----------------------------------------------------------------- GetCharSet ----------------------------------------------------------------- Purpose: Copies one or more character definitions from the active character definition table in use by the BIOS to an user defined buffer. Each character is defined in an 8 bits rows by 32 lines matrix. Each screen scan line is represented by one byte (8 bits). VGA monitors normally use the first 16 bytes, EGA 14 and CGA 8, but the BIOS uses 32 bytes tables for each character. This function can be used before you call the ModifyCharSet function to modify characters so that you can restore them to the original values. See Appendix "J". Prototype: void GetCharSet(int StartCode,int TotalChars, char *Buffer); Returns: Nothing Parameters: StartCode - ASCII code of the first character to store (integer). TotalChars - number of characters to store (integer). Buffer - pointer to a buffer that will contain a bitmap of the stored characters. The buffer size needs to be equal to the number of characters * 32. Example: See ModifyCharSet ----------------------------------------------------------------- GetCharSetAddress ----------------------------------------------------------------- Purpose: Gets the ROM character tables address. You must specify which character table you desire using one of the constants defined in SCL1.H (GCA_8X8A, GCA_8X8B, GCA_8X14, GCA_8X16). Refer to Appendix "J". Prototype: char far * GetCharSetAddress(int table); Returns: Far pointer to one of the BIOS character definition tables stored in ROM. Parameters: Table - character table number (integer). SCL1 Version 3.1 - Reference Manual - Page 101 GetCurCol - GetCurLine - GetCurrentDir ----------------------------------------------------------------- GetCurCol, GetCurLine ----------------------------------------------------------------- Purpose: Returns the current cursor position. Prototype: int GetCurCol(void); int GetCurLine(void); Returns: GetCurCol returns the column position and GetCurLine returns the row position. Parameters: None Example: See PopCursor ----------------------------------------------------------------- GetCurrentDir ----------------------------------------------------------------- Purpose: Returns a string holding the default drive and path. Prototype: int GetCurrentDir(char *PathBuffer); Returns: The DOS error code or "0" if no error occurs. (See Appendix "A", FILE FUNCTIONS, for more information). Parameter: PathBuffer - pointer to a buffer to hold the pathname and drive letter (char). Example: #include <scl1.h> main() { int i,char buffer[160]; i=GetCurrentDir(buffer); if(i) printf("\nDOS reports error #%i\n",i); else printf("\nCurrent directory is %s\n",buffer); } SCL1 Version 3.1 - Reference Manual - Page 102 GetCurSize ----------------------------------------------------------------- GetCurSize ----------------------------------------------------------------- Purpose: Saves the current cursor size in variable GCS_CursorSize and returns the current cursor size. Prototype: int GetCurSize(void); Returns: The current cursor size. Parameters: None Example: #include <scl1.h> main() { int i; i=GetCurSize(); printf("\nCursor size has been saved in local variable, hit any key...\n"); GetKey(); BigCursor(); printf("\nCursor size has been modified, original size will be restored by passing\n"); printf("original size value to SetCursize function, hit any key...\n"); GetKey(); SetCurSize(i); } SCL1 Version 3.1 - Reference Manual - Page 103 GetDate ----------------------------------------------------------------- GetDate ----------------------------------------------------------------- Purpose: Gets the system date. Prototype: struct DateData * GetDate(void); Returns: A pointer to the DateData structure defined as follows: struct DateData{ int WeekDay; day of the week in numerical format (0=sunday). int MonthDay; day of the month (1 - 31). int Month; month number (1 - 12). int Year; year (1980 - 2099). }; Parameters: None Example: #include <scl1.h> char *Day[]={"Sunday","Monday","Tuesday","Wednesday","Thursday", "Friday","Saturday"}; char *Month[]={"","January","February","March","April","May","June", "July","August","September","October","November","December"}; 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 an index to the week and months names arrays we have previously defined.*/ printf("Today is %s, %s %d,%d",Day[p->WeekDay], Month[p->Month],p->MonthDay,p->Year); } SCL1 Version 3.1 - Reference Manual - Page 104 GetDefaultDrive - GetDiskFreeSpace ----------------------------------------------------------------- GetDefaultDrive ----------------------------------------------------------------- Purpose: Gets the default disk drive. Prototype: int GetDefaultDrive(void); Returns: The default drive number, 0=A, 1=B, etc. Parameters: None Example: #include <scl1.h> main() { int Drive; Drive=GetDefaultDrive(); printf("The default drive is %c\n",'A'+Drive) } ----------------------------------------------------------------- GetDiskFreeSpace ----------------------------------------------------------------- Purpose: Gets the selected disk drive's free space in bytes. Prototype: 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. Parameter: Drive - drive number as an integer (for example; 0 - default, 1-A, 2-B, etc.) Example: #include <scl1.h> main() { printf("Disk Free Space=%li\n",GetDiskFreeSpace(0)); } SCL1 Version 3.1 - Reference Manual - Page 105 GetExtendedAscii ----------------------------------------------------------------- GetExtendedAscii ----------------------------------------------------------------- Purpose: Changes ALT+Key combination into Extended Ascii character according to 4 tables Prototype: 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 αßΓπΣσµτΦ ΘΩδ∞φε∩≡ ±≥≤⌠⌡÷≈√ ² Parameter: Key - Scan and ASCII code of a key (unsigned int). Example: #include <scl1.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); } SCL1 Version 3.1 - Reference Manual - Page 106 GetFiles ----------------------------------------------------------------- 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. Prototype: int GetFiles(char *SearchString,int SearchAtr); Returns: The DOS error code or "0" if no 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]); } } SCL1 Version 3.1 - Reference Manual - Page 107 GetFileMode ----------------------------------------------------------------- GetFileMode ----------------------------------------------------------------- Purpose: Gets the selected file's attributes. Prototype: int GetFileMode(char *Filename,int *FMode); Returns: The DOS error code or "0" if no error occurs. (See Appendix "A", FILE FUNCTIONS, for more information). Parameters: Filename - pointer to the file's name. Fmode - pointer to a variable that will hold the file mode (int). 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); } PrintFMode(unsigned int FMode) { SCL1 Version 3.1 - Reference Manual - Page 108 GetFileMode - GetFilePt printf("\nFile attributes:\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"); } ----------------------------------------------------------------- GetFilePt ----------------------------------------------------------------- Purpose: Gets the file's pointer position. Prototype: long GetFilePt(int Handle); Returns: The file pointer position of the file whose handle is Handle or "-1" if a critical error is detected. (See Appendix "A", FILE FUNCTIONS, for more information). Parameter: 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"}; SCL1 Version 3.1 - Reference Manual - Page 109 GetFilePt 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"); } SCL1 Version 3.1 - Reference Manual - Page 110 GetFileSize - GetFreeMem ----------------------------------------------------------------- GetFileSize ----------------------------------------------------------------- Purpose: Gets the size of the selected file. Prototype: long GetFileSize(int Handle); Returns: The size of the file whose handle is Handle or "-1" if a critical error is detected. (See Appendix "A", FILE FUNCTIONS, for more information). Parameter: Handle - Handle returned by DOS when you open or create a file (integer). Example: See GetFilePt ----------------------------------------------------------------- GetFreeMem ----------------------------------------------------------------- Purpose: Gets the free memory reported by DOS in your system. Prototype: long GetFreeMem(void); Returns: The amount of free memory, in bytes, reported by DOS. Parameters: None Example: #include <scl1.h> main() { printf("Available memory: %li",GetFreeMem()); } SCL1 Version 3.1 - Reference Manual - Page 111 GetKey ----------------------------------------------------------------- GetKey ----------------------------------------------------------------- Purpose: Waits and returns the pressed key's Scan/ASCII code. If the CheckEnhancedKeyb function has been called and an enhanced keyboard has been detected, GetKey will also return the Scan/ASCII codes of the extra keys in the enhanced keyboard. Prototype: 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; if(CheckEnhancedKeyb()) printf("Enhanced Keyboard\n"); else printf("No Enhanced Keyboard available\n"); do { switch(Key=GetKey()) { case ENH_ENTER: case ENTER: printf("Enter\n"); break; case ENH_DEL: case DEL: printf("Delete\n"); break; case ENH_INS: case INS: printf("Insert\n"); break; case ENH_END: case END: printf("End\n"); break; SCL1 Version 3.1 - Reference Manual - Page 112 GetKey case ENH_CTRLEND: printf("Enhanced Control End\n"); break; case CTRLEND: printf("Control End\n"); break; case F11: printf("F11\n"); break; case F12: printf("F12\n"); break; case SHIFTF11: printf("Shift F11\n"); break; case SHIFTF12: printf("Shift F12\n"); break; case CTRLF11: printf("Control F11\n"); break; case CTRLF12: printf("Control F12\n"); break; case ALTF11: printf("Alt F11\n"); break; case ALTF12: printf("Alt F12\n"); break; default: printf("%X\n",Key); break; } }while(Key != ESC); } SCL1 Version 3.1 - Reference Manual - Page 113 GetString ----------------------------------------------------------------- GetString ----------------------------------------------------------------- Purpose: Saves the cursor position, displays a prompt, the current buffer contents and fills the buffer with keyboard input. If variable GS_Insert is set to "1" prior to calling GetString, it will start in the insert mode. When an entry has been made into the buffer the variable GS_Edit is set to "1". If GS_Beep is set to "1" the speaker will sound if an invalid key is pressed. The buffer must be initialized. Prototype: int GetString(int PColor,int PRow,int PCol, char* Prompt,int FColor,int FRow,int FCol, int MaxChar,unsigned int CharType,char *Buffer); 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 (int). 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 (int). MaxChar - length of the input field (integer). CharType - mask of valid characters as described in CheckChar. Buffer - pointer to the buffer to be used to store the field, it must be one digit larger than the field's size. Example: #include <scl1.h> char Buffer[32]; main() { GetString(7,10,20,"Name:",0x70,10,28,31,CC_ANY,Buffer); } SCL1 Version 3.1 - Reference Manual - Page 114 GetTime - Huge2Far ----------------------------------------------------------------- GetTime ----------------------------------------------------------------- Purpose: Gets the system time. Sets global variables GT_Hours, GT_Minutes, GT_Seconds and GT_Hundredths to the system time. Prototype: char *GetTime(void); Returns: A pointer to a buffer that holds the system time in ASCII. Parameters: None Example: #include <scl1.h> main() { WriteScreen(0x7,3,3,"Time:"); WriteScreen(0x7,3,9,GetTime()); } ----------------------------------------------------------------- Huge2Far ----------------------------------------------------------------- Purpose: Converts a huge pointer to a far pointer. It is used to convert huge pointers before passing them to an SCL1 function. (Works only in the compact and large models of the Microsoft C version of SCL1). The function prototype is declared in SCL1HUGE.H Prototype: far* Huge2Far(huge* p); Returns: A far pointer. Parameter: p - huge pointer to be converted. Example: #include <SCL1HUGE.H> main() { char *p; huge *h; p=Huge2Far(h); } SCL1 Version 3.1 - Reference Manual - Page 115 HideMouse - ShowMouse ----------------------------------------------------------------- HideMouse, ShowMouse ----------------------------------------------------------------- Purpose: Hides or removes the mouse cursor from the screen (HideMouse) or makes mouse cursor visible (ShowMouse). Prototype: void HideMouse(void); 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"); } SCL1 Version 3.1 - Reference Manual - Page 116 InitDrive - InitMouse ----------------------------------------------------------------- InitDrive ----------------------------------------------------------------- Purpose: Verifies if a disk drive has been assigned more than one logical drive letters and sets the drive to respond to a specified letter. Requires DOS 3.2 or higher. This function is useful to prevent DOS from displaying the "Insert Diskette in Drive X:". Prototype: int InitDrive(int Drive); Returns: If an error has occurred it returns "-1" else it returns "0". Parameter: Drive - drive number as an integer (for example; 0 - default, 1-A, 2-B, etc.) Example: InitDrive(1); /* makes sure drive A: is ready */ ----------------------------------------------------------------- InitMouse ----------------------------------------------------------------- Purpose: Initializes the mouse for further use of the mouse functions. When you exit the program it takes care of resetting the mouse. Prototype: int InitMouse(int Cursor); Returns: If an error has occurred it returns "-1". Parameter: Cursor - this parameter tells InitMouse how to handle the mouse cursor. The following variables have been defined in SCL1.H; IM_SHOW - means to show the mouse cursor (int). IM_NO_SHOW - means not to show the mouse cursor (integer). Example: See HideMouse SCL1 Version 3.1 - Reference Manual - Page 117 InitUserError ----------------------------------------------------------------- InitUserError ----------------------------------------------------------------- Purpose: Initialize user defined error codes for use with the ErrorBox function. You can also redefine the standard ErrorBox messages. Prototype: 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 is terminated with a "0"). struct ErrorMess{ int ErrorNum; An integer value for the error number. User defined values shall be above 256. If a predefined error message is redefined, the function will use the new values. char *Message; Pointer to the defined error message's text. }; Example: See ErrorShadowOn/Off ----------------------------------------------------------------- InitVideo ----------------------------------------------------------------- Purpose: Initialize video monitor to the alphanumeric display mode. Prototype: 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"); } SCL1 Version 3.1 - Reference Manual - Page 118 InitWData ----------------------------------------------------------------- InitWData ----------------------------------------------------------------- Purpose: This version of SCL1 provides another way of defining and using windows. In these windows you can specify shadow effect, frames, grow and shrinking effects, justification method, etc. This information can now be specified using a WData type structure. Once the window is defined you can use the CreateWindow function to create the window; ClearWindow to clear the window; DestroyWindow to destroy the window and WriteWindow to write information to the window. This function provides an easy way to initialize this structure. The structure elements HorSize, VerSize, HorCenter, VerCenter and Buffer are automatically initialized. Prototype: void InitWData(WData *wd,int Color,int Style, int UpperRow,int LeftCol,int LowerRow, int RightCol,int FrameType,int TitleColor, char * Title); Returns: Nothing Parameters: The window data is stored in a structure WData as follows: typedef struct{ int Color; Color to be used for the window. int Style; Defines the way the window will be displayed. Refer to the Style description below. int FrameType; Frame type to be used. int UpperRow; Upper left row position of the window. int LeftCol; Upper left column position of the window. int LowerRow; Lower right row position of the window. int RightCol; Lower right column position of the window. int TitleColor; Color to be used for displaying the title. int *Title; Title's text. SCL1 Version 3.1 - Reference Manual - Page 119 InitWData int HorSize; Structure element (internal) that holds the window's horizontal size excluding the frame. This information can be used to calculate the window's center for writing text. int VerSize; Structure element (internal) that holds the window's vertical size excluding the frame. int HorCenter; Structure element (internal) that holds the window's horizontal center. int VerCenter; Structure element (internal) that holds the window's vertical center. char *Buffer; Buffer for storing the screen area contents. }WData; The following parameters are passed to the function: WData - the address of the WData structure. Color - color to be used for the window (integer). Style - defines the way the window will be displayed. You can concatenate different style options using the "or" (|) operator between options. The following style options have been defined in SCL1.H: W_SAVE - save the screen area defined for the window. W_CLEAR - clear screen area to the defined color. W_FRAME - add a frame to the window. W_GROW - use a growing effect when displaying the window. W_SHRINK - use a shrinking effect when removing the window. W_SHADOW - display a shadow effect. UpperRow - upper left row position of the window (integer). LeftCol - upper left column position of the window (integer). LowerRow - lower right row position of the window (integer). RightCol - lower right column position of the window (int). FrameType - any of the frame types defined in Box or GSSBox (int). SCL1 Version 3.1 - Reference Manual - Page 120 InitWData TitleColor - color to be used for displaying the Title (int). Title - Title to be displayed (char pointer). Example: #include <scl1.h> #include <scl1clor.h> main() { WData wd; /* Define a window from rows 5 to 17, columns 19 to 59, with frame type 3, white black colors, and with the following styles; save screen area, draw a shadow effect, draw a frame, grow when opening, shrink when closing and add title. */ InitWData(&wd,WHITE_BLACK,W_SAVE | W_SHADOW | W_FRAME | W_GROW | W_SHRINK,5,28,19,73,3,BLACK_WHITE," WINDOW TITLE "); CreateWindow(&wd); /* create the window */ /* Display centralized text in the first row of the window, use HorCenter as column parameter to centralize text use HorSize so that the Horizontal window size is used as Count parameter. */ WriteWindow(&wd,1,wd.HorCenter,wd.HorSize,W_CENTER,"Text can be\ncentralized..."); WaitTime(300); /* Display left justified string */ WriteWindow(&wd,5,1,wd.HorSize,W_LEFT,"Left\njustified..."); WaitTime(300); /* Display right justified string. Use HorSize to know the window right column value. */ WriteWindow(&wd,8,wd.HorSize-2,wd.HorSize,W_RIGHT,"or right\n justified..."); WaitTime(300); SCL1 Version 3.1 - Reference Manual - Page 121 InitWData - Int24ShadowOff - Int24ShadowOn /* Clear the window */ ClearWindow(&wd); /* Display string with new lines and tab control codes. Use VerCenter to centralize the string vertically. */ WriteWindow(&wd,wd.VerCenter,1,wd.HorSize,W_LEFT,"New lines\n and\t\tTab control codes are supported..."); WaitTime(300); ClearWindow(&wd); /* This string is longer than window size, it will be clipped */ WriteWindow(&wd,wd.VerCenter,22,wd.HorSize,W_LEFT,"This line will be clipped..."); WaitTime(300); /* Remove window from screen */ DestroyWindow(&wd); } ----------------------------------------------------------------- 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. Prototype: void Int24ShadowOff(void); void Int24ShadowOn(void); Returns: Nothing. Parameters: None. See TrapInt24 and SetTrapInt24Colors. SCL1 Version 3.1 - Reference Manual - Page 122 I24_SetUserLang ----------------------------------------------------------------- I24_SetUserLang ----------------------------------------------------------------- Purpose: Modify the default TrapInt24 error messages with your own error messages. Prototype: void I24_SetUserLang(char *prompt1,int offset1, unsigned int key1,char *prompt2,int offset2, unsigned int key2,struct ErrorMess *em) Returns: Nothing Parameters: The error messages are defined in a null terminated array of structures as follows: struct ErrorMess{ int ErrorNum; Error number of the message to modify. char *Message; Pointer to the new error message. }; The following are the default error messages: ERROR DESCRIPTION 0 Write-protected diskette! 2 Drive not ready! 4 CRC Data error 6 Seek error 8 Sector not found 9 Printer out of paper! 10 Write fault 11 Read fault 12 General failure 0 Printer not ready! 0 Unknown Critical Error The following parameters are passed to the function: prompt1 - char pointer to the first prompt ("Retry") action. offset1 - position from the border of the box where to display the first prompt (integer). key1 - key to be used for selecting prompt1 (unsigned int). prompt2 - char pointer to the second prompt ("Cancel") action. SCL1 Version 3.1 - Reference Manual - Page 123 I24_SetUserLang - KeyReady offset2 - position from the border of the box where to display the second prompt (integer). key2 - key to be used for selecting prompt2 (unsigned int). em - pointer to the ErrorMess structure. Example: static struct ErrorMess CtrErrs[]={ /* error code, message */ 0,"¡Disco protegido!", 2,"¡El lector no está listo!", 4,"Error de data en disco", 6,"Error buscando en disco", 8,"Imposible encontrar sector", 9,"¡Impresora sin papel!", 10,"Error de escritura", 11,"Error de lectura", 12,"Falla general", 0,"¡La impresora no está lista!", 0,"Error crítico desconocido", 0}; I24_SetUserLang("< TRATAR >",6,0x1454,"< CANCELAR >",18,0x2e43,CtrErrs); ----------------------------------------------------------------- KeyReady ----------------------------------------------------------------- Purpose: Scans the BIOS keyboard buffer for unprocessed keystrokes. Prototype: unsigned int KeyReady(void); Returns: 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(); } SCL1 Version 3.1 - Reference Manual - Page 124 KeyStatus ----------------------------------------------------------------- KeyStatus ----------------------------------------------------------------- Purpose: Returns the shift, control and toggle key status. Supports extended keyboards if CheckEnhancedKeyb has been previously called. Prototype: unsigned char KeyStatus(void); Returns: The return value AND the following masks, defined in SCL1KEYS.H, are ">0" if the key is toggled or pressed. The mask values for standard keyboards defined in SCL1KEYS.H are: INSERT, CAPSL, NUML, SCROLL, ALT, CTRL, LSHIFT and RSHIFT. The additional mask values for enhanced keyboards defined in SCL1KEYS.H are: LEFT_CTRL, LEFT_ALT, RIGHT_CTRL, RIGHT_ALT, SCROLL_DOWN, NUML_DOWN, CAPSL_DOWN and SYSREQ. Example: #include <scl1.h> #include <scl1keys.h> /* shows the use of the KeyStatus functions */ main() { unsigned int KStat,OldKStat; KStat=KeyStatus(); do { OldKStat = KStat; if(KStat & ALT) printf("\n\nALT ON "); else printf("\n\nALT OFF"); if(KStat & LSHIFT || KStat & RSHIFT) printf("\t\tSHIFT ON "); else printf("\t\tSHIFT OFF"); SCL1 Version 3.1 - Reference Manual - Page 125 KeyStatus if(KStat & CTRL) printf("\tCONTROL ON "); else printf("\tCONTROL OFF"); if(KStat & INSERT) printf("\tINSERT ON "); else printf("\tINSERT OFF"); if(KStat & CAPSL) printf("\nCAPS LOCK ON "); else printf("\nCAPS LOCK OFF"); if(KStat & NUML) printf("\tNUM LOCK ON "); else printf("\tNUM LOCK OFF"); if(KStat & SCROLL) printf("\tSCROLL LOCK ON "); else printf("\tSCROLL LOCK OFF"); printf("\n\nPress any other key to exit\n"); do { KStat=KeyStatus(); }while(KStat == OldKStat && !KeyReady()); if(KeyReady()==INS) ClearKeyBuf(); }while(!KeyReady()); ClearKeyBuf(); } SCL1 Version 3.1 - Reference Manual - Page 126 LeapYear ----------------------------------------------------------------- LeapYear ----------------------------------------------------------------- Purpose: Determines if a year is leap or not. Prototype: int LeapYear(int year); Returns: Returns "1" if the year passed as a parameter is leap or "0" if it is not leap. Parameter: year - year in the YYYY format (integer). Example: /* This is the source of the DaysPerMonth function */ void DaysPerMonth(year,month) { switch (month) { case 1: case 3: case 5: case 7: case 8: case 10: case 12: return(31); case 4: case 6: case 9: case 11: return(30); case 2: return(28+LeapYear(year)); } } SCL1 Version 3.1 - Reference Manual - Page 127 LineEditor ----------------------------------------------------------------- LineEditor ----------------------------------------------------------------- Purpose: A full featured line editor. You can define most display parameters such as; where to display a prompt, size of the field, size of the display, colors, cursor size, default editing mode, etc. Prototype: 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. Returns a message described in the Messages section. Parameters: Dialog type functions receive messages and structures as 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; Color attribute for the prompt. int PRow; Row position for the prompt's display. int PCol; Column position for the prompt's display. char *Prompt; Char pointer to the prompt. int FColor; Color attribute for the field. int FRow; Row position for the field's display. int FCol; Column position for the field's display. unsigned int FLength; Number of characters to display. unsigned int FSize; Maximum number of characters of the field. If FSize is larger than FLength, the display will scroll horizontally when the cursor reaches the end of the display length. SCL1 Version 3.1 - Reference Manual - Page 128 LineEditor int CType; Type of characters to be accepted. Please refer to CheckChar for a description of the values defined in SCL1.H. int MaskFn; Flag to instruct the function to accept or discard the characters defined in the MaskArray array. A "0" value will accept the characters and a "1" value will discard them. char *MaskArray; Array of mask characters (null terminated). char *Buffer; Buffer that holds the information to be edited. char *FormatC; String that holds the characters to be used as format characters (such as / to delimit date fields, etc.). unsigned int *ExitKeys; Null terminated array of unsigned integer Scan/Ascii values of the keys to exit. int InsFlag; Flag to instruct the function of the default edit mode. ("1" = Insert, "0" = typeover). int InsertCur; Size of cursor when insert mode is toggled ("0" = none, "1" = normal, "2" = block sized). int TypeOverCur; Size of cursor when typeover mode is toggled ("0"= none, "1" = normal, "2" = block sized). int 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. unsigned int StartPos; Start position of conditional paint. unsigned int EndPos; End position of conditional paint. unsigned int EventInfo; Information about pressed keys. SCL1 Version 3.1 - Reference Manual - Page 129 LineEditor unsigned int Position; Contains the current cursor position within the buffer (or offset). unsigned int Scroll; Horizontal scroll counter, keeps track of the cursor position when the field size is larger than the field length. int Edited; 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. }LEData; 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 set by SetDialogColors. FColor - set to black characters in a white background or the reversed color set by SetDialogColors. FLength and 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. LE_ACTIVE - edit the contents of the field buffer. The following edit keys have been defined: SCL1 Version 3.1 - Reference Manual - Page 130 LineEditor 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. CTRL+Left cursor to previous word CTRL+Right cursor to next word LE_KEY - the parameter passed with this messages (Scan+Ascii code of the key) is a key value that performs as if the key has been pressed. LE_DATA - the parameter passed with this messages is an ASCII 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. 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. SCL1 Version 3.1 - Reference Manual - Page 131 LineEditor 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 to the 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> /* Shows the use of LineEditor function. See the example 2 for another example of 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); SCL1 Version 3.1 - Reference Manual - Page 132 LineEditor /* modify prompt and field position */ led.PRow=led.FRow=12; led.PCol=25; led.FCol=35; led.FLength=20;/* the field's screen length is of 20 characters*/ led.FSize=80; /* but up to 80 characters can be entered, the data entry field will scroll automatically */ 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(); Cls(WHITE_BLACK,CLS_ALL); /* clear screen */ } /**************************************************************** #include <scl1.h> #include <scl1keys.h> #include <scl1clor.h> /* Shows the use of LineEditor function using a mask to define acceptable characters. A '@' accepts letters and # accepts digits, * accepts any character. */ char mask[]="@@##@"; /* mask to be used */ unsigned int ExitKeys[]={ENTER,ESC,0}; /* LineEd exit keys */ main() { LEData led; int Mess; SCL1 Version 3.1 - Reference Manual - Page 133 LineEditor char buffer[6]; 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.FRow=12; led.FCol=35; led.FLength=5; /* the field's screen length is of 5 characters*/ led.FSize=5; led.CType=CC_ANY; /* 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 */ CheckMask(&led); /* call our function to check mask*/ /* loop until an exit key is pressed */ }while(Mess != LE_EXIT_KEY); Cls(WHITE_BLACK,CLS_ALL); /* clear screen */ } CheckMask(LEData *led) { int i; /* each time called this function will check the string in LineEditor and compare it with the mask */ i=strlen(led->Buffer)-1; SCL1 Version 3.1 - Reference Manual - Page 134 LineEditor while(i >= 0) { switch(mask[i]) { /* digits only */ case '#': if(!isdigit(led->Buffer[i])) goto Invalid; break; case '@': /* letters only */ if(!isalpha(led->Buffer[i])) goto Invalid; break; case '*': /* accept anything */ return; } --i; } return; /* In case an invalid character is detected we'll move LineEditor position to the invalid character. If insert mode is on (InFlag) we'll send the CHARS_DOWN message to LineEditor so that all characters that follow the invalid character are moved down. If insert mode is off we'll copy a space character to the current position. */ Invalid: { led->Position=i; if(led->InsFlag) LineEditor(LE_CHARS_DOWN,led); else led->Buffer[i]=' '; LineEditor(LE_DRAW,led); /* redraw */ TSound(440,10); } } SCL1 Version 3.1 - Reference Manual - Page 135 LinkedList ----------------------------------------------------------------- LinkedList ----------------------------------------------------------------- Purpose: Manages linked lists. Prototype: int LinkedList(int Mess,LLData *ld,...); Returns: This is a dialog derived function. See Appendix "E" for a description of the general operation of these functions. Returns the messages described in the Messages section. Parameters: The linked list information is given in structures type LLData as follows: typedef struct{ unsigned int DataSize; The size of the data block. char *Data; Pointer to user defined data. unsigned int Nodes; Variable (internal) that holds the quantity of nodes in the list. unsigned int ActiveNode; Variable (internal) that holds the active node number. LLNODE *Head; Pointer (internal) to the first node of the list. LLNODE *Tail; Pointer (internal) to the last node of the list. LLNODE *Position; Pointer (internal) to the active node of the list. }LLData; The structure LLNODEtag can be checked to find out the pointers to the next and previous nodes. For most applications you will not have to worry about this structure. struct LLNODEtag{ struct LLNODEtag *Next; Pointer to the next list node. struct LLNODEtag *Prev; Pointer to the previous list node. unsigned int DataSize; The size of the data block. char *Data; Pointer to user defined data. } SCL1 Version 3.1 - Reference Manual - Page 136 LinkedList Messages: The following messages can be sent to LinkedList: LL_INIT - initialize the LLData structure to null. LL_ADD - add a node to the list. LL_NEXT - move to the next node in the list. LL_PREVIOUS - move to the previous node in the list. LL_FIRST - move to the first node in the list. LL_LAST - move to the last node in the list. LL_DELETE - delete a node from the list. LL_DELETE_ALL - delete all nodes. LL_INSERT - insert a node in the list. LL_SET_POSITION - set the node pointer to a desired position. LL_REPLACE - replace a node in the list. LL_SAVE_POSITION - saves a position in the list for further reference. LL_RESTORE_POSITION - returns to the node previously saved with the LL_SAVE_POSITION message. The following messages can be returned by LinkedList: LL_OK - no errors were found while performing a requested action. LL_MEM_ERROR - there is not enough memory to store the linked list. LL_LAST_NODE - you have reached the last node of the list. LL_FIRST_NODE - you have reached the beginning of the list. LL_EMPTY_LIST - the linked list is empty. LL_ILLEGAL_POSITION - you have requested to move the record pointed to an illegal position. SCL1 Version 3.1 - Reference Manual - Page 137 LinkedList Example: #include <scl1.h> #include <scl1keys.h> #include <string.h> #include <malloc.h> /* This example shows the use of the LinkedList to create and manage a linked list */ main() { LLData ld; char buffer[20]; int i,Mess; unsigned int key=0; InitVideo(); LinkedList(LL_INIT,&ld); /* init */ /* add 20 elements to list */ for(i=0;i < 20;++i) { sprintf(buffer,"line #%i",i); ld.DataSize=strlen(buffer)+1; /* elements can have different sizes */ ld.Data=buffer; /* point to our data */ LinkedList(LL_ADD,&ld); } LinkedList(LL_FIRST,&ld); /* move to first position */ printf("%s size:%i\r\n",ld.Data,ld.DataSize); Mess=LL_OK; do { switch(key) /* translate keystroke to message */ { case UP: Mess=LL_PREVIOUS; break; case DOWN: Mess=LL_NEXT; break; case HOME: Mess=LL_FIRST; SCL1 Version 3.1 - Reference Manual - Page 138 LinkedList break; case END: Mess=LL_LAST; break; case INS: /* let user insert new element */ memset(buffer,0,sizeof(buffer)); if(DialogBox(7,"Text:",0x70,10,CC_ANY,buffer)!=-1) { ld.Data=buffer; /* points to new data */ ld.DataSize=strlen(buffer)+1; /* equals size in bytes */ Mess=LinkedList(LL_INSERT,&ld); } Mess=0; break; case DEL: Mess=LL_DELETE; break; case ENTER: /* let user modify data */ strcpy(buffer,ld.Data); if(DialogBox(7,"Text:",0x70,10,CC_ANY,buffer)!=-1) { ld.Data=buffer; ld.DataSize=strlen(buffer)+1; /* replace previous data */ Mess=LinkedList(LL_REPLACE,&ld); Mess=0; } break; case F2: /* let user modify position */ if(DialogBox(7,"Position:",0x70,10,CC_DIGIT,buffer)!=-1) Mess=LinkedList(LL_SET_POSITION,&ld,atoi(buffer)); break; default: Mess=0; break; } SCL1 Version 3.1 - Reference Manual - Page 139 LinkedList - ListManager /* send message to LinkedList */ if(Mess) { Mess=LinkedList(Mess,&ld); /* display data at current position, ld.Data points to our data ld.DataSize equals size in byes */ if(Mess!=LL_EMPTY_LIST) printf("%s size:%i\r\n",ld.Data,ld.DataSize); else printf("Empty list\r\n"); /* no data */ } }while((key=GetKey()) != ESC); LinkedList(LL_DELETE_ALL,&ld); } ----------------------------------------------------------------- ListManager ----------------------------------------------------------------- Purpose: Displays a list of items and permits user selection of items. Prototype: int ListManager(int NColor,int RColor,int Number, int Length,int Selection,int Lines,int Cols, struct ItemList*p); Returns: 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; Row position of where to display the item. int Col; Column position where to display the item. char *String; Char pointer to the item text to be displayed. }; The parameters passed to the function are: NColor - color for the normal display of items (integer). RColor - color for the highlighted item (integer). SCL1 Version 3.1 - Reference Manual - Page 140 ListManager Number - number of items defined (integer). Length - length of the items (integer). Selection - default selection (integer). Lines - number of lines to be displayed (integer). 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. SCL1 Version 3.1 - Reference Manual - Page 141 ListWindow ----------------------------------------------------------------- ListWindow ----------------------------------------------------------------- Purpose: Displays an array of items in a window in columnar form. The user can use the keyboard or mouse to tag or select a desired item. For a large list of items, scroll bars are displayed to indicate that there are items not shown. Prototype: 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. Returns a message described in the Messages section. Parameters: Dialog type functions receive messages and structures as parameters. The list window information is given in a structure defined as type LWData as follows: typedef struct{ int NColor; Color for normal display. int RColor; Color for reversed display. int UpperRow; Upper row position of the window. int LeftCol; Left column position of the window. int LowerRow; Lower row position of the window. int RightCol; Right column position of the window. int FrameType; Frame type as defined in Box. int ScrollBar; Flag to select drawing scroll bars at the bottom of the display. int BarColor; Color for the scroll bars. char **Array; Pointer to a null terminated array of pointers to be displayed. char *TagArray; Array that holds which items have been tagged. If a null pointer is specified no tagging will be permitted. Array element values of "0" and "1" indicate the status for untagged and tagged. SCL1 Version 3.1 - Reference Manual - Page 142 ListWindow int TagColor; Color for displaying a tagged item. char *Title; Char pointer to text to be displayed as a window title. int TitleColor; Color for the title's display. unsigned int *ExitKeys; Null terminated array of keys to exit the function. int StaticWidth; A value of "0" means that the number of columns will be determined by the length of the items, a value of "1" sets the width of the columns to the value defined with ColumnWidth. unsigned int Items; Variable (internal) that holds the quantity of items in the array. unsigned int ColumnWidth; Width of each column to be displayed. unsigned int FirstItem; Variable (internal) that holds the position of the first array element. unsigned int Position; Variable (internal) that holds the active position of the display. This element should not be modified by the calling program but can be read. unsigned int *ExitKeys; Array of keys to exit the function. int WindowLines; Number of lines in the List Window (used internally). int WindowCols; Variable (internal) that holds the number of columns in the List Window. int TotalCols; Variable (internal) that holds the maximum number of columns in the window. int TotalWindowItems; Variable (internal) that holds the number of items. SCL1 Version 3.1 - Reference Manual - Page 143 ListWindow int OldHBlock; Variable (internal) that holds the position of the relative position indicating scroll bar block). unsigned int EventInfo; Information about the keys that have been pressed. }LWData; 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 set by SetDialogColors. RColor - set to black characters in a white background or the reversed color set by SetDialogColors. LowerRow and RightCol - one less than the screen length. 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 set by SetDialogColors. TagColor - set to black characters in a white background or the reversed color set by SetDialogColors. TitleColor - set to white characters in a black background or the normal color set by SetDialogColors. OldHBlock - set to "-1". LW_DRAW - display the list window. LW_WRITE - displays the list of items to the screen. LW_ACTIVE - browse through the displayed items and permit the selection or tagging of them using the keyboard as follows: SCL1 Version 3.1 - Reference Manual - Page 144 ListWindow 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 - reset the position variables to default values. If exit keys have not been defined they are set to the default exit keys. LW_MBAR_CHARS - this message is used to change the characters used for the scroll bars display. Default characters are defined in header file SCL1.H as LW_MBAR_DEF (character for the background) and LW_THUMB_DEF (character to display the relative position). Pass the desired characters as additional parameters (for example, ListWindow(LW_MBAR_CHARS, &swd, LW_MBAR_DEF, 254);). 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 - an exit key has been pressed. SCL1 Version 3.1 - Reference Manual - Page 145 ListWindow 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 undefined 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. Example: #include <scl1.h> #include <scl1clor.h> /* ListWindow example */ 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]; SCL1 Version 3.1 - Reference Manual - Page 146 ListWindow - LW_MoveTo - SW_MoveTo main() { int EMess; LWData lw; /* set lw as type LWData */ Cls(7,CLS_ALL); ListWindow(LW_INIT,&lw); lw.UpperRow=5; /* Set window size */ lw.LowerRow=9; lw.LeftCol=20; lw.RightCol=34; lw.RColor=WHITE_BLACK+HIGHLIGHT; lw.TagArray=TagA; /* tag array */ lw.Array=Items; /* data */ ListWindow(LW_DRAW,&lw); /* draw */ InitMouse(IM_SHOW); do { EMess=ListWindow(LW_ACTIVE,&lw); if(EMess==LW_ILLEGAL_KEY) LW_MoveTo(&lw); }while(EMess != LW_EXIT_KEY); } ----------------------------------------------------------------- LW_MoveTo, SW_MoveTo ----------------------------------------------------------------- Purpose: These functions are used with ListWindow (LW_MoveTo) and ScrollWindow (SW_MoveTo). When ListWindow and ScrollWindow return an illegal key message, these functions permit you to move the cursor position to first item that starts with the Ascii character of the key pressed. Prototype: int LW_MoveTo(LWData *lwd); int SW_MoveTo(SWData *sw); Returns: Returns the position where the first item that matches the key pressed is located. Parameters: Each function requires you to specify a pointer to the corresponding structure, LWData for List and SWData for ScrollWindow. Example: See ListWindow and ScrollWindow SCL1 Version 3.1 - Reference Manual - Page 147 MCR_CloseFile - MCR_Init ----------------------------------------------------------------- MCR_CloseFile ----------------------------------------------------------------- Purpose: Closes a macro file. Prototype: int MCR_CloseFile(void); Returns: The DOS error code or "0" if no error occurs. (See Appendix "A", FILE FUNCTIONS, for more information). Parameters: None Example: See MCR_Init ----------------------------------------------------------------- MCR_Init ----------------------------------------------------------------- Purpose: Initialize or start the macro handling process. Prototype: void MCR_Init(unsigned int Key,int (* userf) (int flag,MACROData *md)); Returns: Nothing. Parameters: Key - the key that will be used to start or stop the macro definition process (unsigned integer). userf - pointer to a function that will be called when the user selects to start or stop the macro recording process. The user function receives two parameters, an action message (flag) and a pointer to a MACROData structure. The following messages are defined: MACRO_START - The first time the key defined to record macros (the Key parameter) is pressed, the user function receives a MACRO_START message. The user function must specify the structure that will be assigned to the macro, the buffer to store the keystrokes and the maximum size. The size shall be one integer (two bytes) larger than the maximum macro size. All this information is included in the MACROData structure. SCL1 Version 3.1 - Reference Manual - Page 148 MCR_Init MACRO_STOP - The next time the key defined to start/stop macros is pressed, the function receives a MACRO_STOP message. This instructs your user function that the macro has been recorded. The actual macro size will be stored in the "size" parameter of the MACROData structure. Your user function can also receive the MACRO_REPORT or NO_MACRO messages from the MCR_Report function. The user function must check these messages and act accordingly. (Please refer to the MCR_Report function). The user function must return a value of "0" to indicate the calling function that no problems have been found in the macro handling process. If the user function returns a "-1" the macro will not be recorded. The macro information is stored in a structure type MACROData as follows: typedef struct{ unsigned int key; key to trigger or invoke the macro. unsigned int size; Maximum number of keys to accept for the macro (the macro size). unsigned int *buffer; Pointer to the buffer that will hold the macro, this buffer must be able to store one character more than the desired number of keys. }MACROData; Example: #include <scl1.h> #include <scl1keys.h> #include <malloc.h> struct ErrorMess em[]={/* Messages for problems creating macros*/ 1000,"The selected key is\nalready in use.", 1001,"Error creating macro file", 0}; macrof(int mess,MACROData *md); /* User defined macro processing function */ main() { LEData led; /* A LineEditor will be used to get keys */ char buffer[81]; /* Buffer for storing keys */ SCL1 Version 3.1 - Reference Manual - Page 149 MCR_Init Cls(7,CLS_ALL); InitUserError(em); memset(buffer,0,sizeof(buffer)); LineEditor(LE_INIT,&led); /* Line Editor initialization */ led.Buffer=buffer; led.Prompt="Press F10 to define a macro"; led.FRow=1; led.FLength=80; led.FSize=80; LineEditor(LE_DRAW,&led); /* initialize macros, the parameters needed are: key to start/stop the macro definition and the user defined function that will be called */ MCR_Init(F10,macrof); /* Read any macros that might have been stored in file KEYB.MCR*/ MCR_ReadFile("KEYB.MCR"); /* Activate Line Editor until an Exit Key is pressed */ while(LineEditor(LE_ACTIVE,&led) != LE_EXIT_KEY); /* Before leaving, scan memory for macro functions and report them to the user defined macro handling function*/ MCR_Report(); } /* This is the user defined macro handling function, it is called each time a macro recording is started or stopped and by MCR_Report */ macrof(int mess,MACROData *md) { unsigned int key; switch(mess) /* The parameter received is a message from the macro function */ { case MACRO_START: /* The key defined for starting/stopping the macro recording process has been pressed for the first time */ /* Place a message on the screen */ MessageOn(0x70,"Enter Macro key...\nPress F10 to end macro"); SCL1 Version 3.1 - Reference Manual - Page 150 MCR_Init do { key=GetKey(); /* Check if the key is already in use. MCR_MacroExist returns "1" if that key is already in use */ if(key==F10 || MCR_MacroExist(key)) ErrorBox(1000); else break; }while(1); /* The MACROData structure holds the macro information, its elements are: key - key to trigger macro. buffer - pointer to the buffer to store keys (max keys + 1) size - max number of keys to accept */ md->key=key; /* Save key into structure */ /* Allocate memory */ md->buffer=(unsigned int *)calloc(100,sizeof(int)); if(md->buffer==0) mess=-1; /* do not record macro */ else { mess=0; /* OK record macro */ md->size=99; /* set an initial size / } MessageOff(); break; case MACRO_STOP: /* The key defined for starting/stopping the macro recording process has been pressed for the second time */ md->size = the number of key pressed + 1 use this to resize allocated buffer */ MessageOn(7,"MACRO RECORDED"); WaitTime(100); MessageOff(); SCL1 Version 3.1 - Reference Manual - Page 151 MCR_Init md->buffer=realloc(md->buffer,md->size * sizeof(unsigned int)); mess=0; break; case MACRO_REPORT: MCR_Init - MCR_MacroEnable - MCR_MacroDisable /* We have asked for a macro report (call MCR_Report function). Macros will be reported one by one. md holds the macro info*/ if(MCR_SaveMacro("KEYB.MCR",md)) /* Start saving macros to disk file KEYB.MCR */ { ErrorBox(1001); mess=-1; } else mess=0; break; case MACRO_NO_MACRO: /* MCR_Report indicates that no more macros could be found */ if(MCR_CloseFile()) ErrorBox(1001); mess=0; break; } return(mess); } SCL1 Version 3.1 - Reference Manual - Page 152 MCR_MacroEnable - MCR_MacroDisable - MCR_MacroExist ----------------------------------------------------------------- MCR_MacroEnable, MCR_MacroDisable ----------------------------------------------------------------- Purpose: These functions permit the programmer to enable or disable the macro capabilities. They are useful if you want to temporarily disable the keyboard macro trapping while a routine waits for keyboard input, etc. Prototype: void MCR_MacroDisable(void); void MCR_MacroEnable(void); Returns: Nothing. Parameters: None ----------------------------------------------------------------- MCR_MacroExist ----------------------------------------------------------------- Purpose: This function verifies if a given keyboard combination has been previously assigned to a macro. Prototype: int MacroExist(unsigned int Key); Returns: Returns "0" if the key has not been assigned to a macro or "1" if that key has been assigned. Parameter: Key - Key to be verified if a macro has already been assigned (unsigned integer), refer to file SCL1KEYS.H. Example: See MCR_Init SCL1 Version 3.1 - Reference Manual - Page 153 MCR_Play - MCR_ReadFile ----------------------------------------------------------------- MCR_Play ----------------------------------------------------------------- Purpose: This function permits you to play a macro definition. Prototype: void MCR_Play(unsigned int *macro); Returns: Nothing Parameter: macro - pointer to a macro defined as a null terminated array of scan/ascii codes of the keys. Example: #include <scl1.h> #include <scl1keys.h> /* macro defined as a null terminated array of key scan codes */ unsigned int macro1[]={0x1e61,0x3062,0x2e63,0x2064,0}; MCR_Play(macro1); /* ask macro func. to play macro1 */ ----------------------------------------------------------------- MCR_ReadFile ----------------------------------------------------------------- Purpose: Opens a file for retrieving macros. Prototype: int MCR_ReadFile(char *FileName); Returns: The DOS error code, "0" if no error occurs or "255" if there is not enough memory to retrieve the macros from the file. (See Appendix "A", for more information). Parameter: FileName - char pointer to the filename to be used for storing or retrieving macros. Example: See MCR_Init SCL1 Version 3.1 - Reference Manual - Page 154 MCR_Record - MCR_RegisterBackF ----------------------------------------------------------------- MCR_Record ----------------------------------------------------------------- Purpose: This function permits you to start a macro definition. It offers an alternative to start macro recording without the use of a hot key, like from a menu. Prototype: void MCR_Record(void); Returns: Nothing Parameters: None ----------------------------------------------------------------- MCR_RegisterBackF ----------------------------------------------------------------- Purpose: This function permits your program to trap a given key. The function checks if the key has been pressed each time there is keyboard activity, and when it detects that it has been pressed it calls a user function defined as a parameter. Prototype: void MCR_RegisterBackF(void(*userf)(void)); Returns: Nothing Parameter: userf - pointer to an user defined function that will be called in the background when no keys are being processed. SCL1 Version 3.1 - Reference Manual - Page 155 MCR_RegisterMacro ----------------------------------------------------------------- MCR_RegisterMacro ----------------------------------------------------------------- Purpose: This function permits to add a macro. This function provides an alternate way to add macros to memory. Prototype: int MCR_RegisterMacro(unsigned int Key, unsigned int size,unsigned int *Buffer); Returns: Returns "0" if the macro has been successfully defined or "1" if there is not sufficient memory to store the macro. Parameters: key - the key to trigger or invoke the macro (unsigned integer). size - the maximum number of keys to accept for the macro (unsigned integer). buffer - pointer to the buffer that will hold the macro, this buffer must be able to store one character more than the desired number of keys (unsigned integer). Example: unsigned int Macrobuf[]={'M','a','c','r','o',0}; MCR_RegisterMacro(CTRLF1,sizeof(Macrobuf),Macrobuf); SCL1 Version 3.1 - Reference Manual - Page 156 MCR_RegisterTrapKey - MCR_Report ----------------------------------------------------------------- MCR_RegisterTrapKey ----------------------------------------------------------------- Purpose: This function permits your program to trap a given key. The function checks if the key has been pressed each time there is keyboard activity, and when it detects that it has been pressed it calls a user function defined as a parameter. Prototype: int MCR_RegisterTrapKey(unsigned int Key, int (* userf)()); Returns: Returns "0" if the key has been successfully trapped or "1" if there is not enough memory available to store the information. Parameters: Key - Key to be trapped (unsigned integer), most keys have been defined in header file SCL1KEYS.H. userf - pointer to an user defined function that will be called every time the trapped key is pressed. ----------------------------------------------------------------- MCR_Report ----------------------------------------------------------------- Purpose: Scans the memory for defined macros and reports the macros found to the function that is processing the macros. Sends a message to the macro user function a MACRO_REPORT message each time it finds a macro or MACRO_NO_MACRO when it does not finds any more macros. Your user function can use this messages to manage the macros. See example. Prototype: void ReportMacro(void); Returns: Nothing Parameters: None Example: See MCR_Init SCL1 Version 3.1 - Reference Manual - Page 157 MCR_SaveMacro ----------------------------------------------------------------- MCR_SaveMacro ----------------------------------------------------------------- Purpose: Opens a file, if not open, and saves a macro in memory to the file. Prototype: int MCR_SaveMacro(char *FileName,MACROData *md); Returns: The DOS error code or "0" if no error occurs. (See Appendix "A", FILE FUNCTIONS, for more information). Parameters: The macro data information is given in a structure type MACROData as follows: Structure type MACROData; typedef struct{ unsigned int key; Key to trigger or invoke the macro. unsigned int size; Maximum number of keys to accept for the macro. unsigned int *buffer; Pointer to the buffer that will hold the macro, this buffer must be able to store one character more than the desired number of keys. }MACROData; The parameters passed to the function are: FileName - pointer to the filename to be used for storing or retrieving macros (char). md - pointer to the MACROData structure. Example: See MCR_Init SCL1 Version 3.1 - Reference Manual - Page 158 MCR_UnregisterBackF - MCR_UnregisterMacro - MCR_UnregisterTrapKey ----------------------------------------------------------------- MCR_UnregisterBackF ----------------------------------------------------------------- Purpose: This function permits your program to release a background function previously defined using the MCR_RegisterBackF function. Prototype: void MCR_UnregisterBackF(void); Returns: Nothing. Parameters: None ----------------------------------------------------------------- MCR_UnregisterMacro ----------------------------------------------------------------- Purpose: This function permits to remove a previously defined macro. Prototype: unsigned int *MCR_UnregisterMacro(unsigned int Key); Returns: Returns a pointer the macro buffer. Parameter: key - key assigned to trigger or invoke the macro (unsigned int). ----------------------------------------------------------------- MCR_UnregisterTrapKey ----------------------------------------------------------------- Purpose: This function permits your program release trapping of a given key. The key must have been previously trapped using the MCR_RegisterTrapKey function. Prototype: void MCR_UnregisterTrapKey(unsigned int Key); Returns: Nothing. Parameter: Key - Key that has been previously trapped (unsigned int). SCL1 Version 3.1 - Reference Manual - Page 159 MakeDir ----------------------------------------------------------------- MakeDir ----------------------------------------------------------------- Purpose: Creates a new directory. Prototype: int MakeDir(char *Path); Returns: The DOS error code or "0" if no error occurs. (See Appendix "A", FILE FUNCTIONS, for more information). Parameter: Path - char pointer to a string holding the new directory name. Example: #include <scl1.h> char Dir[]="SCL1"; main() { int i; printf("\nCreating SCL1 directory...\n"); i=MakeDir(Dir); if(i) { printf("\nUnable to create directory\n"); exit(-1); } else printf("SCL1 directory has been created.\n"); printf("\nDeleting SCL1 directory...\n"); i=RemoveDir(Dir); if(i) printf("\nUnable to remove directory\n"); else printf("SCL1 directory has been deleted.\n"); } SCL1 Version 3.1 - Reference Manual - Page 160 Menu - MouseMenu - MouseMenu2 ----------------------------------------------------------------- Menu, MouseMenu, MouseMenu2 ----------------------------------------------------------------- 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 key. With MouseMenu you can also make a selection by moving the mouse cursor to the desired line and clicking the left mouse button. MouseMenu2 is identical to MouseMenu but will let you specify a default selection. Prototype: int Menu(int NColor,int RColor,int HColor,int NumOpt, struct MenuOpt *mo); int MouseMenu(int NColor,int RColor,int HColor, int NumOpt,struct MenuOpt *k,int XMin,int XMax, int YMin,int YMax); int MouseMenu2(int NColor,int RColor,int HColor, int NumOpt,struct MenuOpt *mo,int XMin,int XMax, int YMin,int YMax,int StartSel); Returns: The 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; Row position for the menu item. int Col; Column position for the menu item. char *String; Pointer to the menu item text. char Letter; Letter to be highlighted for fast keyboard selection of the menu item. }; The parameters passed to the function are: NColor - color for the menu background and foreground (int). RColor - color for the highlighted item menu bar (integer). HColor - color for the highlighted quick selection menu item letter (integer). SCL1 Version 3.1 - Reference Manual - Page 161 Menu - MouseMenu - MouseMenu2 NumOpt - number of menu options (integer). MenuOpt - pointer to the menu structure previously defined. For MouseMenu only; 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). For MouseMenu2 only; StartSel - default selection (integer). Example: #include <scl1.h> #include <scl1clor.h> /* Shows the use of Menu, MouseMenu and MouseMenu2 */ struct MenuOpt Mainm[7]={/*Array of structures with 7 elements */ 5,26,"Screen Related Functions ",'S', /* First option */ 7,26,"Keyboard Handling Functions ",'K', /* Second option */ 9,26,"Mouse Handling Functions ",'M', /* Third option */ 11,26,"Program Flow Functions ",'P',/* Fourth option */ 13,26,"File Handling Functions ",'F',/* Fifth option */ 15,26,"Background and Miscellaneous",'B',/* Sixth option */ 17,26,"Exit Demo ",'E',/* Seventh option */ }; main() { int Selection; Cls(WHITE_BLACK,CLS_ALL); Box(WHITE_BLACK,1,3,24,18,55); /* Box for menu */ WriteScreen(WHITE_BLACK,3,38,"MENU"); /* Menu title */ /* Menu */ Selection=Menu(WHITE_BLACK,BLACK_WHITE,WHITE_BLACK+HIGHLIGHT,7, Mainm); Cls(WHITE_BLACK,CLS_ALL); SCL1 Version 3.1 - Reference Manual - Page 162 Menu - MouseMenu - MouseMenu2 if(Selection > 0) printf("You have selected option %i, press any key...\n", Selection); else printf("You have pressed ESCAPE, press any key...\n"); GetKey(); InitMouse(IM_SHOW); /* MouseMenu */ Cls(WHITE_BLACK,CLS_ALL); Box(WHITE_BLACK,1,3,24,18,55); /* Box for menu */ WriteScreen(WHITE_BLACK,3,35,"MOUSE MENU"); /* Menu title */ Selection=MouseMenu(WHITE_BLACK,BLACK_WHITE,WHITE_BLACK+ HIGHLIGHT,7,Mainm,24,55,3,18); 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"); WaitKeyMouse(); /* MouseMenu2 - with MouseMenu2 you can select the option that will be active when the menu first appears (last parameter)*/ Cls(WHITE_BLACK,CLS_ALL); Box(WHITE_BLACK,1,3,24,18,55); /* Box for menu */ WriteScreen(WHITE_BLACK,3,35,"MOUSE MENU2 ");/* Menu title */ Selection=MouseMenu2(WHITE_BLACK,BLACK_WHITE,WHITE_BLACK+ HIGHLIGHT,7,Mainm,24,55,3,18,3); 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"); } SCL1 Version 3.1 - Reference Manual - Page 163 MenuSystem - MenuSystem2 ----------------------------------------------------------------- MenuSystem, MenuSystem2 ----------------------------------------------------------------- Purpose: Displays a pull-down menu system. The function requires to define various structures and data blocks. MenuSystem2 is identical to MenuSystem except that it provides the capability to display a text string associated with each menu option and of "greying" out options (making options unavailable under certain conditions). Prototype: int MenuSystem(int Message,MSData *msd,...); int MenuSystem2(int Message,MSData2 *msd,...); Returns: This are dialog type functions. See Appendix "E" for a description of the general operation of these functions. Returns a message described in the Messages section. Parameters: Dialog type functions receive messages and structures as parameters. The information is given as follows: 1. The top row menu information is defined as an array of structures type MSBar (for MenuSystem) or MSBar2 (for MenuSystem2) as follows, one element for each of the main options: typedef struct{ int StartCol; Column position of the first character of the option's prompt. int EndCol; Column position of the last character of the option's prompt. unsigned int Key; Key (or combination) that will be used to call the pull-down menu. (Necessary when using keyboard input). char *String; Pointer to a string containing the option's prompt. }MSBar; Notes: A. The MSBar and MSBar2 structures are identical. Two different names have been used to prevent confusion. B. The StartCol and EndCol information is used to determine the mouse range for that option and to highlight it when selected. For proper operation make sure that options do not overlap. SCL1 Version 3.1 - Reference Manual - Page 164 MenuSystem - MenuSystem2 2. Each pull-down menu is defined as an array of structures type MSOptions (for MenuSystem) or MSOptions2 (for MenuSystem2). The structure is similar to that used for the Menu function: typedef struct{ int Row; Row position for the menu item. int Col; Column position for the menu item. char *String; Pointer to the menu item text. char Letter; Letter to be highlighted for fast keyboard selection of the menu item. }MSOptions; typedef struct{ int Row; Row position for the menu item. int Col; Column position for the menu item. char *String; Pointer to the menu item text. char Letter; Letter to be highlighted for fast keyboard selection of the menu item. int Active; Status of the option. "1" makes the option available and a "0" unavailable. char *Text; Pointer to a text string that will be displayed when the corresponding menu option is highlighted. }MSOptions2; 3. The pull down menu box information is defined in a structure type MSWindows (for MenuSystem) or MSWindow2 (for MenuSystem2), as an array of structures for the menu system, one element for each pull-down menu as follows: typedef struct{ int UpperRow; Upper row position of the box used to enclose the pull-down menu. int LeftCol; Left column position of the box. int LowerRow; Lower row position of the box. int RightCol; Right column position of the box. SCL1 Version 3.1 - Reference Manual - Page 165 MenuSystem - MenuSystem2 int Number; Number of options in the pull-down menu. char *WinBuffer; Buffer to store the screen area, used when popping out the pull-down menu. MSOptions *mso; Pointer to the MSOptions structure corresponding to that pull-down menu. }MSWindow; typedef struct{ int UpperRow; Refer to the MSWindow structure int LeftCol; " " int LowerRow; " " int RightCol; " " int Number; " " char *WinBuffer; " " MSOptions2 *mso; Pointer to the MSOptions2 structure corresponding to that pull-down menu. }MSWindow2; 4. The remaining information is defined in a structure type MSData (for MenuSystem) or MSData2 (for MenuSystem2) as follows: typedef struct{ int BarNColor; Normal color for top row or bar menu. int BarRColor; Reversed color for top row menu. int MenuNColor; Normal color for the pull-down menus. int MenuRColor; Reversed color for the pull-down menus. int MenuHColor; Highlight color for hot-keys. MSBar *msb; Pointer to the MSBar structure. MSWindow *msw; Pointer to the MSWindow structure. int Number; Number of pull-down menus in the system. SCL1 Version 3.1 - Reference Manual - Page 166 MenuSystem - MenuSystem2 int Menu; Holds the active pull-down menu number. int Option; Holds the active option of the selected pull-down menu. unsigned int EventInfo; Event information for the Menu System. }MSData; typedef struct{ Refer to the MSData structure int BarNColor; " " int BarRColor; " " int MenuNColor; " " int MenuRColor; " " int MenuHColor; " " int MenuGNColor; Normal color for the "grayed" (unavailable) out menu options. int MenuGRColor; Reversed color for the "grayed" out menu options. MSBar2 *msb; Pointer to the MSBar2 structure. MSWindow2 *msw; Pointer to the MSWindow2 structure. int Number; Refer to the MSData structure int Menu; " " int Option; " " unsigned int EventInfo; " " int TextColor; Color to be used for displaying the text related to menu option. int TextRow; Row position for displaying the text. int TextCol; Column position for displaying the text. int TextLength; Length of the text }MSData2; SCL1 Version 3.1 - Reference Manual - Page 167 MenuSystem - MenuSystem2 Messages: The following messages can be sent to MenuSystem and MenuSystem2: 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 set by SetDialogColors. BarRColor - set to white characters in a black background or the normal color set by SetDialogColors. MenuNColor - set to white characters in a black background or the normal color set by SetDialogColors. MenuRColor - set to black characters in a white background or the reversed color set by SetDialogColors. MenuHColor - set to highlighted white characters in a black background or the highlight color set by 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. SCL1 Version 3.1 - Reference Manual - Page 168 MenuSystem - MenuSystem2 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). MS_SET_BAR_ROW - set 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_SHOW_MENU - enable the display of the menu system. MS_HIDE_MENU - disable the display of the menu system. 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's 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. MS_RESET - reset the menu system to the default values. The following messages can be returned by MenuSystem and MenuSystem2: 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. SCL1 Version 3.1 - Reference Manual - Page 169 MenuSystem - MenuSystem2 Example: #include <scl1.h> #include <scl1keys.h> #include <scl1clor.h> /* MenuSystem example */ 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]; /* Pull-down menu box & window information top left corner and bottom right corner positions number of options buffer for saving screen area MSOptions structure */ SCL1 Version 3.1 - Reference Manual - Page 170 MenuSystem - MenuSystem2 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); do { /* a key pressed? */ if(Mess=KeyReady()) { SCL1 Version 3.1 - Reference Manual - Page 171 MenuSystem - MenuSystem2 /* 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; case 3: /* third option */ MessageOn(BLACK_WHITE,"Quit"); WaitTime(100); SCL1 Version 3.1 - Reference Manual - Page 172 MenuSystem - MenuSystem2 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); } SCL1 Version 3.1 - Reference Manual - Page 173 MenuSystem - MenuSystem2 /**************************************************************** MenuSystem2 example. You can display a help-line and grayed-out menu items with MenuSystem2 */ #include <scl1.h> #include <scl1keys.h> #include <scl1clor.h> MSBar2 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 1=active,0=inactive option help text */ MSOptions2 mso0[]={ 2,1," Load ",'L',1,"Load new file", 3,1," Save ",'S',0,"Save edited file", /* inactive option*/ 4,1," Quit ",'Q',1,"Exit to DOS", }; /* second pull-down menu */ MSOptions2 mso1[]={ 2,7," Mark ",'M',1,"Mark block", 3,7," Cut ",'C',1,"Cut text block", 4,7," Copy ",'y',1,"Copy text block", 5,7," Paste ",'P',1,"Paste text block", }; /* buffer for storing pull down menu screen area */ char WindowBuf[140]; /* Pull-down menu box & window information top left corner and bottom right corner positions number of options buffer for saving screen area MSOptions structure */ SCL1 Version 3.1 - Reference Manual - Page 174 MenuSystem - MenuSystem2 MSWindow2 msw[]={ 1,0,5,7,3,WindowBuf,mso0, 1,6,6,14,4,WindowBuf,mso1, }; /* This structure links all previous structures */ MSData2 msd= { /* bar-menu colors */ BLACK_WHITE,WHITE_BLACK+HIGHLIGHT, /* pull-down menu colors */ WHITE_BLACK,BLACK_WHITE,WHITE_BLACK+HIGHLIGHT, /* normal and reverse color for inactive options */ BLACK_BLACK+HIGHLIGHT,BLACK_WHITE+HIGHLIGHT, /* MSBar, MSWindow structures, number of menus and internal variables */ msb,msw,2,0,0,0, /* text color, line, column, and length */ BLACK_WHITE,24,0,80}; main() { int Mess; InitMouse(IM_SHOW); /* initialize mouse */ /* Draw shadows */ MenuSystem2(MS_SHADOW_ON,(MSData *)0); /* MenuSystem2 will be ALT sensitive */ MenuSystem2(MS_ALT_ON,(MSData *)0); /* draw */ MenuSystem2(MS_DRAW,&msd); do SCL1 Version 3.1 - Reference Manual - Page 175 MenuSystem - MenuSystem2 { /* a key pressed? */ if(Mess=KeyReady()) { /* send key to MenuSystem2 */ Mess=MenuSystem2(MS_KEY,&msd,Mess); /* If we still have a key it means it was not a MenuSystem2 key, discard key. If your program needs to service the keyboard you should do it here. */ if(KeyReady()) GetKey(); } else /* Let MenuSystem2 check if the mouse has been clicked or a selection has been made */ Mess=MenuSystem2(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; SCL1 Version 3.1 - Reference Manual - Page 176 MenuSystem - MenuSystem2 case 2: /* second option, since is inactive we'll never receive this selection*/ MessageOn(BLACK_WHITE,"Save"); WaitTime(100); MessageOff();break; 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; SCL1 Version 3.1 - Reference Manual - Page 177 MenuSystem - MenuSystem2 - MESS_SetPosition case 4: /* fourth option */ MessageOn(BLACK_WHITE,"Paste"); WaitTime(100); MessageOff(); break; } break; } } }while(msd.Menu != 1 || msd.Option != 3); } ----------------------------------------------------------------- MESS_SetPosition ----------------------------------------------------------------- Purpose: Permits changing the position of a MessageOn/Off display to any place in the screen. Prototype: void MESS_SetPosition(int UpperRow,int LeftCol); Returns: Nothing Parameters: UpperRow - upper row position of the Message box (integer). LeftCol - left column position of the Message box (integer). Example: See MessageShadowOn/Off SCL1 Version 3.1 - Reference Manual - Page 178 MessageOff ----------------------------------------------------------------- MessageOff ----------------------------------------------------------------- Purpose: Removes the message box displayed by MessageOn and restores the screen's previous contents. Prototype: 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..."); for(i=0;i < 30000; i++) /* loop */ /* write inside MessageOn screen area */ WriteScreen(WHITE_BLACK,11,38,Bin2Ascii((long)i,buffer)); MessageOff(); /* restore screen */ } See also MessageOn, MessageShadowOff and MessageShadowOn. SCL1 Version 3.1 - Reference Manual - Page 179 MessageOn - MessageShadowOff - MessageShadowOn ----------------------------------------------------------------- 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. Prototype: 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. You can call MessageOn as many times as desired without turning them off with MessageOff. Use MessageOff to restore the screen with its original contents before calling the MessageOn for the first time. Example: See MessageOff See also MessageOff, MessageShadowOff and MessageShadowOn. ----------------------------------------------------------------- MessageShadowOff, MessageShadowOn ----------------------------------------------------------------- Purpose: Displays or disable a shadow effect when using the MessageOn/MessageOff functions. After any of these functions are called subsequent calls to the MessageOn function will be displayed with (or without) a shadow effect. Prototype: void MessageShadowOff(void); void MessageShadowOn(void); Returns: Nothing. Parameters: None. SCL1 Version 3.1 - Reference Manual - Page 180 MessageShadowOff - MessageShadowOn Example: #include <scl1.h> #include <scl1clor.h> main() { int i; /*Clear screen so that shadow effect can be seen */ Cls(BLACK_WHITE,CLS_ALL); MESS_SetPosition(4,10);/*Place Message box in row 4, col 10 */ MessageOn(WHITE_BLUE,"MessageOn function without shadow\nPress any key..."); GetKey(); MessageOff(); MessageShadowOn(); MessageOn(WHITE_BLUE,"MessageOn function WITH shadow \nPress any key..."); GetKey(); MessageOff(); MessageShadowOff(); MessageOn(WHITE_BLUE,"MessageOn function again\nwithout shadow\nPress any key..."); GetKey(); MessageOff(); } See MessageOn and MessageOff. SCL1 Version 3.1 - Reference Manual - Page 181 ModifyCharSet ----------------------------------------------------------------- ModifyCharSet ----------------------------------------------------------------- Purpose: Lets you redefine or modify one or more characters when using VGA or EGA display adapters. The character data is passed as a bitmap of 9 X 14 pixels (for EGA), 9 X 16 pixels (for VGA) or 8 X 8 pixels (for CGA). Once a character is redefined it can be displayed using the ASCII code corresponding to that character. You can convert small bitmapped drawings into a series of consecutive characters using the included BMPCNV.C utility program. The drawing must be saved using the Windows 3.0 BMP format. To use the utility program you must first compile and link it. The comments on the file explain its usage. This program may also help to explain how to use the character set functions. See Appendix "J". Prototype: void ModifyCharSet(int Points,int StartCode, int TotalChars,char *Bits); Returns: Nothing Parameters: Points - number of scan lines used for the character as per the following table (integer): MODE POINTS 80 x 25 16 VGA 80 x 28 14 80 x 50 8 EGA 80 x 25 14 80 x 43 8 StartCode - ASCII code of the first character to modify (integer). TotalChars - number of characters to modify (integer). Bits - pointer to an array that contain a bitmap of the character definition. SCL1 Version 3.1 - Reference Manual - Page 182 ModifyCharSet Example: #include <scl1.h> /* This file shows the use of GetCharSet and ModifyCharSet to modify VGA and EGA character definition tables */ /* copyright symbol for the VGA */ char VGAcopyr[]={0x00,0x00,0x00,0x0f,0x18,0x33,0x26,0x26,0x26, 0x26,0x33,0x18,0x0f,0x00,0x00,0x00,0x00,0x00, 0x00,0xf8,0x0c,0xe6,0x22,0x02,0x02,0x22,0xe6, 0x0c,0xf8,0x00,0x00,0x00}; /* copyright symbol for the EGA */ char EGAcopyr[]={0x00,0x00,0x0f,0x18,0x33,0x26,0x26,0x26,0x26, 0x33,0x18,0x0f,0x00,0x00,0x00,0x00,0xf8,0x0c, 0xe6,0x22,0x02,0x02,0x22,0xe6,0x0c,0xf8,0x00, 0x00}; main() { unsigned char OldChar[32 * 2]; /* Buffer */ VideoConfig(); if(VC_Monitor != VC_VGA && VC_Monitor != VC_EGA) { printf("Your monitor does not support character modification\n"); exit(-1); } /* We will change ASCII characters 192-193 into a copyright symbol but first we'll copy the original characters so that they can be restored later */ GetCharSet(192,2,OldChar); /* Modify character definition */ if(VC_Monitor==VC_VGA) ModifyCharSet(16,192,2,VGAcopyr); else ModifyCharSet(14,192,2,EGAcopyr); SCL1 Version 3.1 - Reference Manual - Page 183 ModifyCharSet - ModifyPalette /* Write the new copyright character */ printf("The new copyright symbol \xc0\xc1, press any key...\n"); WaitKeyMouse(); /* restore characters */ ModifyCharSet(32,192,2,OldChar); printf("Symbols restored\n"); } ----------------------------------------------------------------- ModifyPalette ----------------------------------------------------------------- Purpose: Modify all palette colors. The color array contains seventeen values, 16 colors and the screen border color. See Appendix "J". Prototype: void ModifyPalette(char *Colors); Returns: Nothing Parameters: Colors - Char pointer to an array of new colors containing 17 values, 16 colors and the border color. SCL1 Version 3.1 - Reference Manual - Page 184 ModifyPaletteColor ----------------------------------------------------------------- ModifyPaletteColor ----------------------------------------------------------------- Purpose: Modifies one palette entry. See Appendix "J". Prototype: void ModifyPaletteColor(int Palette,int NewValue); Returns: Nothing Parameters: Palette - palette number (integer). NewValue - new color (integer). Example: #include <scl1.h> #include <scl1keys.h> /* This file shows how to use ModifyPaletteColor to change palette settings in a VGA or EGA monitor */ static char PaldemoText1[]=" Up/Down arrow keys - modify background color background color:\n" "Left/Right arrow keys - modify foreground color foreground color:"; static char PaldemoText2[]="ESC to\n EXIT"; main() { int bcolor=0,fcolor=7; char buffer[12]; unsigned int key; /* We Will modify palette entry 0 (normally black) and palette entry 7 (white) */ InitVideo(); FillBlock(7,0,0,22,79,'X'); /* fill screen */ WriteScreen(7,23,0,PaldemoText1); /* write message */ WriteScreen(7,23,73,PaldemoText2); do { SCL1 Version 3.1 - Reference Manual - Page 185 ModifyPaletteColor /* write palette entry values */ sprintf(buffer,"0x%02x\n0x%02x",bcolor,fcolor); WriteScreen(7,23,67,buffer); switch((key=GetKey())) { case UP: /* let user modify value with keyboard */ if(bcolor < 63) { ++bcolor; ModifyPaletteColor(0,bcolor); /* modify palette */ } break; case DOWN: if(bcolor > 0) { --bcolor; ModifyPaletteColor(0,bcolor); } break; case RIGHT: if(fcolor < 63) { ++fcolor; ModifyPaletteColor(7,fcolor); } break; case LEFT: if(fcolor > 0) { --fcolor; ModifyPaletteColor(7,fcolor); } break; } }while(key != ESC); InitVideo(); /* restore to default */ } SCL1 Version 3.1 - Reference Manual - Page 186 MouseButton ----------------------------------------------------------------- MouseButton ----------------------------------------------------------------- Purpose: A Mouse Button is a prompt that can be placed anywhere in the screen, 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 box. Most functions, like FileBox, use Mouse Buttons (to select or cancel). If you require more than one Mouse Button it is better to use Fields2. Prototype: 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. Returns a message described in the Messages section. Parameters: Dialog type functions receive messages and structures as parameters. The MouseButton information must be given in a structure, type MBData, as follows: typedef struct{ int NColor; Color used for an unselected button. int RColor; Color used for a selected button. int UpperRow; Upper row position of the Button area. int LeftCol; Left column position of the Button area. int LowerRow; Lower row position of the Button area. int RightCol; Right column position of the Button area. int PRow; Row position of the Mouse Button text. int PCol; Column position of the Button text. char *Prompt; Char pointer to the Mouse Button text. SCL1 Version 3.1 - Reference Manual - Page 187 MouseButton int BoxFlag; Flag to indicate if a box shall be drawn around a Mouse Button. int ActiveFlag; Flag to indicate if the Button is active. unsigned int *ExitKeys; Array of keys to exit the function. unsigned int EventInfo; Holds the key pressed when you exit the function or a non defined key is pressed. }MBData; Messages: The following messages can be sent to MouseButton: MB_INIT - initialize the MBData structure to NULL and set the following default values: NColor - white characters in a black background or the normal color set by SetDialogColors. RColor - black characters in a white background or the reversed color set by 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 - reset the Mouse Button variables to the default values. If exit keys have not been defined, 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 - 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. SCL1 Version 3.1 - Reference Manual - Page 188 MouseButton - MoveFilePt 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. Example: #include <scl1.h> #include <scl1clor.h> main() { int EMess; MBData mb1; Cls(WHITE_BLACK,CLS_ALL); MouseButton(MB_INIT,&mb1); mb1.LeftCol=12; mb1.RightCol=19; mb1.NColor=WHITE_BLACK; mb1.RColor=BLACK_WHITE; 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); } ----------------------------------------------------------------- MoveFilePt ----------------------------------------------------------------- Purpose: Moves the file pointer to the current location plus an offset. Prototype: int MoveFilePt(int Handle, unsigned long Bytes); Returns: The DOS error code or "0" if no error occurs. (See Appendix "A"). Parameters: Handle - number is given by DOS when you open a file (integer). Bytes - number of bytes for offset (unsigned long integer). Example: See GetFilePt SCL1 Version 3.1 - Reference Manual - Page 189 MoveFilePt2Offset - Num2Date ----------------------------------------------------------------- MoveFilePt2Offset ----------------------------------------------------------------- Purpose: Moves the file read write pointer to an offset from the beginning of the file. Prototype: 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") Parameters: Handle - number is given by DOS when you open a file (int). Bytes - number of bytes for offset (unsigned long integer). Example: See GetFilePt ----------------------------------------------------------------- Num2Date ----------------------------------------------------------------- Purpose: Converts an unsigned integer number representing the number of elapsed days since January 1, 1900 to the Day/Month/Year/WeekDay format. Prototype: void Num2Date(unsigned int count,int *Month,int *Day, int *Year, int *Weekday) Returns: modifies the variables that holds the date information. Parameters: count - unsigned integer number representing the number of days that have elapsed since January 1, 1900. Month - a valid month number (1 to 28,29, 30 or 31)(integer). Day - a valid month number (1 to 12) (integer). Year - a valid month year (four digits) from 1900 to 2077 (int). WeekDay - an integer representing the day of the week (0=Sunday, etc.) Example: See Date2Num SCL1 Version 3.1 - Reference Manual - Page 190 OpenFile ----------------------------------------------------------------- OpenFile ----------------------------------------------------------------- Purpose: Opens and existing file. Prototype: int OpenFile(char *Filename, int *Handle,char OMode); Returns: The DOS error code or "0" if no error occurs. (See Appendix "A", FILE FUNCTIONS, for more information). Parameters: Filename - pointer to filename (char). Handle - pointer to variable that will hold the DOS handle number (int). OMode - One of several Open modes as defined in SCL1.H: 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. 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. SCL1 Version 3.1 - Reference Manual - Page 191 OpenFile Access mode: DOS3_READ, DOS3_WRITE, DOS3_RW are similar to DOS 2.0. See DOS 3.0 Technical Reference for more information. Example: /* This is the source code of the File2Buf function */ #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)); } SCL1 Version 3.1 - Reference Manual - Page 192 PercentBar ----------------------------------------------------------------- PercentBar ----------------------------------------------------------------- Purpose: Displays a bar that graphically shows the completed and uncompleted percentage of a given process. Prototype: void PercentBar(int Mess,PBData *pbd,...); Returns: This is a dialog derived function. See Appendix "E" for a description of the general operation of these functions. Parameters: The percent bar information is given in a structure type PBData as follows: typedef struct{ int Color; Color to be used for the percent bar. int Row; Row where to start the display of the bar. int Col; Column where to start the display of the bar. int Size; Size (number of columns) of the bar. unsigned int Total; Total percent value to be represented. int ForeChar; Foreground character to be used for displaying the completed portion of the display. int BackChar; Background character to be used for displaying the uncompleted portion of the display. }PBData; Messages: The following messages can be sent to PercentBar: PB_INIT - initialize the PBData structure to NULL and set the following default values: Size - set to 80 column. Total - set to 100 %. ForeChar - set to solid block. BackChar - set to checkered block. SCL1 Version 3.1 - Reference Manual - Page 193 PercentBar - PushCursor - PopCursor FB_DRAW - draw the PercentBar to the screen. FB_UPDATE - update the PercentBar display. Each time the function is called with this message and an additional parameter, holding the percent value, the PercentBar display will increment. Example: #include <scl1.h> main() { PBData pbd; int i; Cls(7,CLS_ALL); PercentBar(PB_INIT,&pbd); pbd.Row=10; pbd.Col=10; pbd.Total=100; pbd.Size=60; PercentBar(PB_DRAW,&pbd); for(i=1;i < 101;++i) { PercentBar(PB_UPDATE,&pbd,i); WaitTime(30); } } ----------------------------------------------------------------- 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 sixty- four. Prototype: int PushCursor(void); int PopCursor(void); Returns: Nothing. Parameters: None. Example: #include <scl1.h> #include <scl1keys.h> SCL1 Version 3.1 - Reference Manual - Page 194 PushCursor - PopCursor /* Shows the use of cursor related functions */ char Text[]="\n\nCursor size and position has been be saved using PushCursor.\n\n" "\t<*> Move the cursor around your screen using the arrow keys\n" "\t<*> Change cursor size using the TAB key\n" "\t<*> Press ESC to restore original size and position\n"; main() { unsigned int Key; int CurFlag=0; printf(Text); PushCursor(); /* save cursor size and position */ /* let user modify size and position */ do { switch((Key=GetKey())) { case UP: SetCurPos(GetCurLine()-1,GetCurCol()); break; case DOWN: SetCurPos(GetCurLine()+1,GetCurCol()); break; case LEFT: SetCurPos(GetCurLine(),GetCurCol()-1); break; case RIGHT: SetCurPos(GetCurLine(),GetCurCol()+1); break; case TAB: CurFlag ^= 1; if(CurFlag) BigCursor(); else CursorOn(); break; } }while(Key != ESC); /* restore original size and position */ PopCursor(); } SCL1 Version 3.1 - Reference Manual - Page 195 PopMenu ----------------------------------------------------------------- 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. Prototype: 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; Upper row position of the box used for the pull-down menu. int C1; Left column position of the box. int L2; Lower row position of the box. int C2; Right column position of the box. int NumberOption; Number of options of the menu. char *WinBuffer; Buffer to store the screen area used when popping out the menu. struct MenuOpt *Menust; Pointer to the MenuOption structure corresponding to that menu. }; The parameters passed to the function are: NColor - color for the menu background and foreground (int). RColor - color for the highlighted item menu bar (integer). HColor - color for the highlighted quick selection menu item letter (integer). PopMenuData - pointer to the PopMenuData structure SCL1 Version 3.1 - Reference Manual - Page 196 PopMenu - ReadFile 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, }; main() { int Selection; Selection=PopMenu(WHITE_BLACK,BLACK_WHITE,BLACK_WHITE+HIGHLIGHT,p md1); } ----------------------------------------------------------------- ReadFile ----------------------------------------------------------------- Purpose: Reads number of bytes from a file Prototype: int ReadFile(int Handle,char *Buffer, unsigned int Bytes); Returns: The DOS error code or "0" if no 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: See OpenFile SCL1 Version 3.1 - Reference Manual - Page 197 ReadPalette - RecordFile ----------------------------------------------------------------- ReadPalette ----------------------------------------------------------------- Purpose: Fills an array with the active palette information. Prototype: int ReadPalette(char *Colors); Returns: "-1" if it cannot read the palette. Parameter: Colors - pointer to an array that contains the palette information. See Appendix "J". Example: #include <scl1.h> main() { char Colors[17]; if (ReadPalette (Colors)==-1); printf("Cannot read palette/n"); } ----------------------------------------------------------------- RecordFile ----------------------------------------------------------------- Purpose: Provides a method for managing record files. Prototype: int RecordFile(int Mess,SFData *sfd); Returns: This is a dialog derived function. See Appendix "E" for a description of the general operation of these functions. Returns the messages described in the Messages section. Parameters: The file information is given in a structure type RFData as follows: typedef struct{ char *FName; Pointer to a valid filename. char *Buffer; Pointer to the buffer that holds the record. unsigned int DataSize; Size of data block. long FPos; Variable (internal) that holds the current record's file pointer (long). SCL1 Version 3.1 - Reference Manual - Page 198 RecordFile long FSize; Variable (internal) that holds the file size. long Entries; Variable (internal) that holds the number of records. int FHandle; Variable (internal) that holds the file handle assigned to the file. int Error; Variable (internal) that contain any errors that have occurred. }RFData; Messages: The following messages can be sent to RecordFile: RF_OPEN - Open a file for record reading or writing. RF_CREATE - Create a file for record reading or writing. RF_FIRST - Move file pointer and read the first record. RF_LAST - Move file pointer and read the last record. RF_NEXT - Move file pointer and read the next record. RF_PREVIOUS - Move file pointer and read previous record. RF_CLOSE - Close file. RF_ADD - Add a record to file. RF_OPENCREATE - Opens a file for record reading or writing or creates the file if it does not exists. RF_WRITE - Write buffer to file. RF_SETPOS - Set the file pointer to the desired record number. RF_READ - Read a record from file. The following messages can be returned by RecordFile: RF_OK - The requested operation was performed without errors. RF_FILENOTFOUND - The specified file was not found. RF_EOF - You have reached the end of the file. SCL1 Version 3.1 - Reference Manual - Page 199 RecordFile RF_BOF - You have reached the beginning of the file. RF_READERR - A read error was encountered. RF_WRITEERR - A write error was encountered. RF_ILLEGALOP - An illegal operation has been requested. Example: #include <scl1.h> /* This example shows the use of the RecordFile function to create and use a data file organized in records */ char buffer[4]; /* data buffer */ /* this data will be stored in a RecordFile file */ char *test[]={"1","2","3","4","5","6","7"}; /* RecordFile struct */ RFData rfd={"TEST.RF",buffer,2,}; main() { int Mess,i; if(Mess=RecordFile(RF_CREATE,&rfd)) /* create file */ { printf("%i\n",Mess); /* error */ exit(-1); } for(i=0;i < 7;++i) /* add records */ { rfd.Buffer=test[i]; if(Mess=RecordFile(RF_ADD,&rfd)) { printf("%i\n",Mess); /* error */ RecordFile(RF_CLOSE,&rfd); exit(-1); } /* read and print file position and size */ printf("Adding record %i, file position: %li, file size: %li\n",i,rfd.FPos,rfd.FSize); } SCL1 Version 3.1 - Reference Manual - Page 200 RecordFile printf("Press any key...\n"); GetKey(); /* make rfd.Buffer point to our buffer so that all data is be copied to our buffer. We will read all records */ printf("Records in the order the were saved\n"); rfd.Buffer=buffer; if(RecordFile(RF_FIRST,&rfd)==RF_OK) /* get first record*/ { do /* print it */ { printf("%s\n",buffer); }while(RecordFile(RF_NEXT,&rfd) != RF_EOF);/* get next */ } printf("Press any key...\n"); GetKey(); printf("Records in reverse order\n"); /* get last record */ if(RecordFile(RF_LAST,&rfd)==RF_OK) { do { printf("%s\n",buffer); }while(RecordFile(RF_PREVIOUS,&rfd) != RF_BOF); /* previous*/ } printf("Press any key...\n"); GetKey(); printf("Record=3 modified to A\n"); /* look for record with data 3 and modify it */ if(RecordFile(RF_FIRST,&rfd)==RF_OK) /* get first */ { do { if(strcmp(buffer,"3")==0) /* equal? */ { strcpy(buffer,"A"); /* modify */ RecordFile(RF_WRITE,&rfd); /* write data */ } }while(RecordFile(RF_NEXT,&rfd) != RF_EOF);/* get next */ } SCL1 Version 3.1 - Reference Manual - Page 201 RecordFile - RemoveDir - RemoveExtension /* show all records */ if(RecordFile(RF_FIRST,&rfd)==RF_OK) { do { printf("%s\n",buffer); }while(RecordFile(RF_NEXT,&rfd) != RF_EOF); } RecordFile(RF_CLOSE,&rfd); /* close file */ GetKey(); } ----------------------------------------------------------------- RemoveDir ----------------------------------------------------------------- Purpose: Removes a directory Prototype: int RemoveDir(char *Path); Returns: The DOS error code or "0" if no error occurs. (See Appendix "A", FILE FUNCTIONS, for more information). Parameter: Path - char pointer to directory string. Example: See MakeDir ----------------------------------------------------------------- RemoveExtension ----------------------------------------------------------------- Purpose: Removes the extension of a filename. Prototype: char *RemoveExtension(char *Filename); Returns: A pointer to the filename buffer. Parameter: Filename - char pointer to filename. Example: #include <scl1.h> char Filename[13]="FILE.C"; main() { printf("%s\n",Filename); printf("%s\n",RemoveExtension(Filename)); } SCL1 Version 3.1 - Reference Manual - Page 202 RenameFile ----------------------------------------------------------------- RenameFile ----------------------------------------------------------------- Purpose: Renames or moves a file. Prototype: int RenameFile(char *OldName,char *NewName); Returns: The DOS error code or "0" if no 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 handle; printf("\nCreating file SCL1.TST...\n"); if(CreateFile("SCL1.TST",&handle,F_ARCHIVE)) printf("\nUnable to create file.\n"); else CloseFile(handle); printf("\nRenaming file SCL1.TST ==> SCL1.BAK...\n"); if(RenameFile("SCL1.TST","SCL1.BAK")) printf("\nUnable to rename file.\n"); else { printf("\nDeleting SCL1.BAK...\n"); DeleteFile("SCL1.BAK"); } } SCL1 Version 3.1 - Reference Manual - Page 203 ResetMouse - ResetMouseCur ----------------------------------------------------------------- ResetMouse ----------------------------------------------------------------- Purpose: Resets mouse to default condition (cursor hidden at the screen center and Interrupt service routine disabled). Prototype: void ResetMouse(void); Returns: Nothing. Parameters: None Example: See CheckMouse ----------------------------------------------------------------- ResetMouseCur ----------------------------------------------------------------- Purpose: Resets mouse cursor to a block character. Prototype: 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,23,2,40,"Mouse cursor set to '*' character"); WaitTime(300); ResetMouseCur(); WriteScreenLen(WHITE_BLACK,23,2,40,"Mouse cursor reset to normal"); WaitTime(300); } else WriteScreenLen(WHITE_BLACK,23,2,40,"No mouse installed."); } SCL1 Version 3.1 - Reference Manual - Page 204 ScreenDump ----------------------------------------------------------------- ScreenDump ----------------------------------------------------------------- Purpose: Displays a screendump array in the screen. A screendump array consists of characters followed by its color attribute byte, terminated with a "0", \n can be used to indicate end of lines. Prototype: 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> /* 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 */ char Array[]={'A',7,'B',0x70,\n,'C',0x70,'D',7,0}; main() { 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 ChangeDumpColor. SCL1 Version 3.1 - Reference Manual - Page 205 ScrollDown - ScrollUp ----------------------------------------------------------------- ScrollDown, ScrollUp ----------------------------------------------------------------- Purpose: Scrolls down (ScrollDown) or up (ScrollUp) a screen area. Prototype: void ScrollDown(int Color,int UpperRow,int LeftCol, int LowerRow,int RightCol,int Scroll); void ScrollUp(int Color,int UpperRow,int LeftCol, int LowerRow,int RightCol,int Scroll); Returns: Nothing Parameters: Color - color of the area to be scrolled (integer). UpperRow - upper row of the area to be scrolled (int). LeftCol - left column of the area to be scrolled (int). LowerRow - lower row of the area to be scrolled (int). RightCol - right column of the area to be scrolled (int). Scroll - number of lines to scroll, if this variable is set to "0" the whole window is cleared (integer). Example: #include <scl1.h> #include <scl1clor.h> char Mess1[]="The screen has been scrolled DOWN 1 line"; char Mess2[]="The screen has been scrolled UP 1 line"; main() { Box(WHITE_BLACK,0,0,0,23,79); WaitTime(200); ScrollDown(WHITE_BLACK,0,0,24,79,1); WriteScreen(BLACK_WHITE,0,Center(Mess1),Mess1); WaitTime(200); ScrollUp(WHITE_BLACK,0,0,24,79,1); WriteScreen(BLACK_WHITE,24,Center(Mess2),Mess2); } SCL1 Version 3.1 - Reference Manual - Page 206 ScrollList ----------------------------------------------------------------- ScrollList ----------------------------------------------------------------- Purpose: Displays a list of items enclosed in a box. The function permits to scroll through the items using the arrow keys or the mouse. To select an item press the ENTER key or click the mouse on it. Prototype: int ScrollList(int NColor,int RColor,int Row, int Col,int Lines,char **p); Returns: 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. The parameters passed to the function are: NColor - color for the normal display of items (integer). RColor - color 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 - pointer to a null terminated array of char pointers. Example: #include <scl1.h> #include <scl1clor.h> char *SList[]={ "Append File", "Browse File", "Copy file", "Delete File", "Merge Files", "Move File", "Sort File", "Tag File", 0}; SCL1 Version 3.1 - Reference Manual - Page 207 ScrollList - ScrollWindow main() { int selection; Cls(7,CLS_ALL); selection=ScrollList(WHITE_BLACK,BLACK_WHITE,5,40,5,SList); SetCurPos(20,0); if(selection > 0) printf("\n%s was selected\n",SList[selection-1]); else printf("\Operation was canceled\n"); } ----------------------------------------------------------------- ScrollWindow ----------------------------------------------------------------- Purpose: Displays a window with a list of items. If the list is larger than the window, or if an item's length is larger than the display width, the display area can scroll both horizontally and vertically. The window can have scroll bars at the right and the bottom to show the relative position of the text within the window. It permits you to scroll through the items using the cursor keys or the mouse. You can tag or untag items by pressing the SPACEBAR or clicking the mouse after pointing to an item. To select an item press the ENTER key or double click the mouse after pointing to the item. Prototype: 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. Returns a message described in the Messages section. Parameters: Dialog type functions receive messages and structures as parameters. The scroll window information must be given in a structure type SWData as follows: typedef struct{ int NColor; Color for normal display. int RColor; Color for reversed display. int UpperRow; Upper row position of the window. SCL1 Version 3.1 - Reference Manual - Page 208 ScrollWindow int LeftCol; Left column position of the window. int LowerRow; Lower row position of the window. int RightCol; Right column of the window. int FrameType; Frame type as defined in Box. int ScrollBar; Flag to tell the function to draw scroll bars. int BarColor; Color for the scroll bars. char **Array; Pointer to a null terminated array of pointers to be displayed. char *TagArray; Array that holds which item has been tagged. If a null pointer is specified the function will not permit tagging. Array element values of "0" and "1" indicate the status for untagged and tagged. int TagColor; Color to be used for displaying tagged items. char *Title; Char pointer to text to be displayed as a title. int TitleColor; Color for the title's display. unsigned int *ExitKeys; Array of keys to exit the function. unsigned int Lines; Variable (internal) that holds the quantity of items in the array. unsigned int Length; Variable (internal) that holds the length of the longest element in the ScrollWindow array. unsigned int TopLine; Variable (internal) that holds the element number that is being displayed in the first line of the window. unsigned int Position; Variable (internal) that holds the active position of the display. Note this element should not be modified by the calling program. SCL1 Version 3.1 - Reference Manual - Page 209 ScrollWindow unsigned int FirstCol; Variable (internal) 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. int OldVBlock; Variable (internal) that holds the position of the vertical relative position scroll bar block. int OldHBlock; Variable (internal) that holds the position of the horizontal relative position scroll bar block. int WindowLines; Variable (internal) that holds the number of lines in the List Window. int WindowCols; Variable (internal) that holds the number of columns in the Window. int VScroll; Variable (internal) that keeps track if a vertical scroll is required. int HScroll; Variable (internal) that keeps track if horizontal scroll is required. unsigned int EventInfo; Information about the keys that have been pressed. }SWData; 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 set by SetDialogColors. RColor - set to black characters in a white background or the reversed color set by SetDialogColors. LowerRow and RightCol - one less than the screen length. FrameType - set to frame type "1" (single line). SCL1 Version 3.1 - Reference Manual - Page 210 ScrollWindow ScrollBar - set to draw scroll bars. BarColor - set to black characters in a white background or the reversed color set by SetDialogColors. TagColor - set to black characters in a white background or the reversed color set by SetDialogColors. TitleColor - set to white characters in a black background or the normal color set by SetDialogColors. OldVBlock - set to "-1". OldHBlock - set to "-1". SW_DRAW - display the Scroll Window with the current parameters. 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 keyboard 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 the item number passed as a parameter. SW_CLS - clear the list window. SW_CHECK_MOUSE - check if the mouse has been clicked after pointing to the area defined by the function. SCL1 Version 3.1 - Reference Manual - Page 211 ScrollWindow SW_UWRITE - similar to SW_WRITE but recalculates all the internal variables and redraws the frame if needed. 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. SW_MBAR_CHARS - this message is used to change the characters used for the scroll bars display. Default characters are defined in header file SCL1.H as SW_MBAR_DEF (character for the background) and SW_THUMB_DEF (character to display the relative position). Pass the desired characters as additional parameters (for example, ScrollWindow(SW_MBAR_CHARS, &swd, SW_MBAR_DEF, 254);). 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 active item. 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. SW_NEW_MOUSEPOS - you have moved the cursor by clicking the mouse after pointing to an item. SCL1 Version 3.1 - Reference Manual - Page 212 ScrollWindow 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> 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.", " Video - Detects if the video adapter in use is", " either Monochrome, CGA or EGA.", " WriteCharBlock - Writes a block of characters.", 0}; unsigned int ExitK[]={ESC,ENTER,0}; main() { int i; SWData sw; /* Scroll Window structure */ CursorOff(); /* Turn off cursor */ InitMouse(IM_SHOW); Cls(WHITE_BLACK,CLS_ALL); ScrollWindow(SW_INIT,&sw); /* Initialize Scroll Window */ sw.UpperRow=2; /* Change default window size */ sw.LeftCol=4; sw.LowerRow=15; sw.RightCol=75; sw.ExitKeys=ExitK; sw.Array=Info; sw.Title="[ Information ]"; ScrollWindow(SW_DRAW,&sw); /* Now, draw the Scroll Window */ SCL1 Version 3.1 - Reference Manual - Page 213 ScrollWindow - Select do /* Browse window until an exit key is pressed*/ { i=ScrollWindow(SW_ACTIVE,&sw); if (i==SW_ILLEGAL_KEY) SW_MoveTo(&sw); }while(i!=SW_EXIT_KEY && i!=SW_MOUSE_EVENT); CursorOn(); Cls(7,CLS_ALL); } ----------------------------------------------------------------- Select ----------------------------------------------------------------- Purpose: Permits the display of various options and let the user select one of them. The active option will be displayed with a check mark between parenthesis (√). You can use the keyboard to move among options. 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. It can either be used alone or as one of the field types for the Fields2 function. Prototype: 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. Returns the messages described in the Messages section. Parameters: Dialog type functions receive messages and structures as parameters. The options must be passed as a null terminated array of structures of the type SData1, one array element for each option: typedef struct{ int Row; Row position where the option is displayed. int Col; Column position where the option is displayed. char *String; Pointer to the text used to identify the option. }SData1; The general information about the Select options are included in a structure type SData2, as follows: SCL1 Version 3.1 - Reference Manual - Page 214 Select typedef struct{ int Color; Color for the display of the select options. int PRow; Row position where to display an optional prompt. int PCol; Column position where to display an optional prompt. char *Prompt; Pointer to an optional prompt or option title. unsigned int *ExitKeys; Array of keys defined as exit keys. int Options; Number of options available. int Position; Default selection. unsigned int EventInfo; Will hold the last illegal or exit key pressed. }SData2; 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: Color - set to black characters in a white background or the reversed color set by 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: SCL1 Version 3.1 - Reference Manual - Page 215 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. Example: #include <scl1.h> #include <scl1clor.h> #include <scl1keys.h> unsigned int MyExitKeys[]={ENTER,ESC,0}; SData1 sd1[]={ 12,35,"Male", 13,35,"Female", 0}; SData2 sd2={WHITE_BLACK,10,32,"Enter your sex:",MyExitKeys}; main() { int Mess; Cls(WHITE_BLACK,0,0,24,79); WriteScreen(WHITE_BLACK,16,22," Use ARROW KEYS to select option,\nPress ENTER to accept, ESC to cancel"); Select(S_RESET,sd1,&sd2); sd2.ExitKeys=MyExitKeys; Select(S_DRAW,sd1,&sd2); do { Mess=Select(S_ACTIVE,sd1,&sd2); }while(Mess != S_EXIT_KEY); SCL1 Version 3.1 - Reference Manual - Page 216 Select - SetBin2AsciiDel if(sd2.EventInfo != ESC) { if(sd2.Position==0) WriteScreen(WHITE_BLACK+BLINK,19,32,"You are a male."); else WriteScreen(WHITE_BLACK+BLINK,19,31,"You are a female"); } else WriteScreen(WHITE_BLACK+BLINK,19,29,"Operation was canceled"); SetCurPos(20,0); exit(0); } ----------------------------------------------------------------- SetBin2AsciiDel ----------------------------------------------------------------- Purpose: Permits changing the comma used to in the display of numbers when using the Bin2Ascii function to periods. Please refer to the Bin2Ascii function. Prototype: void SetBin2AsciiDel(int Character); Returns: Nothing Parameter: Character - character to be used as a separator (integer). Example: #include <scl1.h> main() { long l,int i; char buffer[8]; l=999999; Cls(7,CLS_ALL); SetBin2AsciiDel('.'); for(i=0;i < 6;++i,l/=10) { WriteScreenLen(7,10,10,7,Bin2Ascii(l,buffer)); GetKey(); } } SCL1 Version 3.1 - Reference Manual - Page 217 SetCurPos - SetCurSize ----------------------------------------------------------------- SetCurPos ----------------------------------------------------------------- Purpose: Sets the cursor position. Prototype: void SetCurPos(int Row, int Col); Returns: Nothing Parameters: Row - the desired row position (integer). Col - the desired column position (integer). Example: See PopCursor SetCurSize ----------------------------------------------------------------- SetCurSize ----------------------------------------------------------------- Purpose: Sets the cursor size. Prototype: void SetCurSize(int CursorSize); Returns: Nothing Parameter: CursorSize - the desired cursor size, an unsigned integer value that contains 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> main() { int topline,bottomline; InitVideo(); topline=0; if(Video()==COLOR) bottomline=7; else bottomline=13; SCL1 Version 3.1 - Reference Manual - Page 218 SetCurSize - SetDialogColor - SetErrorBoxColor 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); } } ----------------------------------------------------------------- SetDialogColor ----------------------------------------------------------------- Purpose: Lets you define the colors that will be used when initializing any dialog function structure. Prototype: void SetDialogColor(int NColor,int RColor, int HColor); Returns: Nothing Parameters: NColor - normal color for the dialog functions (integer). RColor - reversed color for the dialog functions (integer). HColor - highlight color for the dialog functions (integer). ----------------------------------------------------------------- SetErrorBoxColor ----------------------------------------------------------------- Purpose: Lets you define the color for the Error Box function. Prototype: void SetErrorBoxColor(int UColor) Returns: Nothing Parameter: UColor - color for Error Box messages (integer). See also ErrorBox. SCL1 Version 3.1 - Reference Manual - Page 219 SetFileMode ----------------------------------------------------------------- SetFileMode ----------------------------------------------------------------- Purpose: Sets a file's attributes (system, hidden, read only, etc.). Prototype: int SetFileMode(char *Filename, int NewMode); Returns: The DOS error code or "0" if no 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); } PrintFMode(unsigned int FMode) { printf("\nFile attributes:\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"); } SCL1 Version 3.1 - Reference Manual - Page 220 SetHorLimit - SetVerLimit ----------------------------------------------------------------- SetHorLimit, SetVerLimit ----------------------------------------------------------------- Purpose: Sets the minimum and maximum mouse horizontal position (SetHorLimit) or verical position (SetVerLimit). Prototype: void SetHorLimit(int Minimum,int Maximum); void SetVerLimit(int Minimum,int Maximum); Returns: Nothing Parameters: Minimum - integer value indicating the minimum position. Maximum - integer value indicating the maximum position. Example: #include <scl1.h> main() { InitMouse(IM_SHOW); if(MSE_MouseFl) { SetHorLimit(39,39); printf("Mouse movement has been limited to column 39"); SetVerLimit(11,11); printf("Mouse movement has been limited to line 11"); while(!MSE_LPress); } else printf("No mouse installed\n"); } SCL1 Version 3.1 - Reference Manual - Page 221 SetInt24Colors - SetMouseCur - SetMouseIsr ----------------------------------------------------------------- SetInt24Colors ----------------------------------------------------------------- Purpose: Lets you define the color for the error display box used by the TrapInt24 function. Prototype: void SetInt24Colors(int NColor, int RColor); Returns: Nothing Parameters: NColor - normal color for the TrapInt24 error display (int). RColor - reversed color for the TrapInt24 error display (integer). ----------------------------------------------------------------- SetMouseCur ----------------------------------------------------------------- Purpose: Sets mouse cursor. Any valid character can be used as the mouse cursor. Prototype: void SetMouseCur(int Character); Returns: Nothing Parameter: Character - character to be used as the mouse cursor (int). Example: See ResetMouseCur ----------------------------------------------------------------- SetMouseIsr ----------------------------------------------------------------- Purpose: Sets an interrupt service routine that is called when the mouse moves or any of its buttons is pressed or released. Prototype: void SetMouseIsr(void); Returns: Nothing The following variables are set according to the mouse status: MSE_LPress is set to "1" when the left button is pressed. SCL1 Version 3.1 - Reference Manual - Page 222 SetMouseIsr MSE_LpX is set to the mouse cursor's horizontal position when the left mouse button is pressed. MSE_LpY is set to the mouse cursor's vertical position when the left mouse button is pressed. MSE_LRel is set to "1" when the left button is released. MSE_LrX is set to the mouse cursor's horizontal position when the left mouse button is released. MSE_LrY is set to the mouse cursor's vertical position when the left mouse button is released. MSE_RPress is set to "1" when the right button is pressed. MSE_RpX is set to the mouse cursor's horizontal position when the right mouse button is pressed. MSE_RpY is set to the mouse cursor's vertical position when the right mouse button is pressed. MSE_RRel is set to "1" when the right button is released. MSE_RrX is set to the mouse cursor's horizontal position when the right mouse button is released. MSE_RrY is set to the mouse cursor's vertical position when the right mouse button is released. MSE_Move is set to "1" when the mouse is moved. MSE_MoveX holds the actual mouse cursor's horizontal position. MSE_MoveY holds the actual mouse cursor's vertical 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. Example: See CheckMouse SCL1 Version 3.1 - Reference Manual - Page 223 SetMousePos ----------------------------------------------------------------- SetMousePos ----------------------------------------------------------------- Purpose: Sets the mouse cursor position. Prototype: void SetMousePos(int X, int Y); Returns: Nothing Parameters: X - integer value indicating the horizontal position. Y - integer value indicating the vertical position. 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."); } SCL1 Version 3.1 - Reference Manual - Page 224 SetShadowColor - SetUserBox ----------------------------------------------------------------- SetShadowColor ----------------------------------------------------------------- Purpose: Sets the shadow color. For 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. Prototype: void SetShadowColor(int Color); Returns: Nothing Parameter: Color - color attribute for the shadow effect (to be XOR'ed with the background color) (integer). Example: See Shadow ----------------------------------------------------------------- SetUserBox ----------------------------------------------------------------- Purpose: Lets you define a different frame type than those available for the Box and GSSBox functions. You must specify this frame as number 12 in these functions. Prototype: void SetUserBox(int UpperLeft,int UpperRight, int LowerLeft, int LowerRight,int UpperSide, int BottomSide,int LeftSide,int RightSide); Returns: Nothing Parameters: UpperLeft - character for the upper left corner of the box frame (integer). UpperRight - character for the upper right corner of the box frame (integer). LowerLeft - character for the lower left corner of the box frame (integer). LowerRight - character for the lower right corner of the box frame (integer). UpperSide - characters to be used for drawing the upper border of the box frame (integer). SCL1 Version 3.1 - Reference Manual - Page 225 SetUserBox - SetUserBoxLine 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). 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); } ----------------------------------------------------------------- SetUserBoxLine ----------------------------------------------------------------- Purpose: Lets you define a line type for drawing lines inside boxes that use lines defined by using the SetUserBox function. Prototype: void SetUserBoxLine(int HLeft,int HRight,int VUpper, int VLower); Returns: Nothing Parameters: HLeft - horizontal left line terminating character (int). HRight - horizontal right line terminating character (int). VUpper - vertical upper line terminating character (integer). VLower - vertical lower line terminating character (integer). Example: This example call will set a user type frame to double line, as defined in standard frame type 0 of the Box and GSSBox functions SetUserBoxLine(201,188,200,189,205,205,186,186); SCL1 Version 3.1 - Reference Manual - Page 226 SetVideoMode ----------------------------------------------------------------- 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. Prototype: void SetVideoMode(int NewMode); Returns: Nothing Parameter: 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); } SCL1 Version 3.1 - Reference Manual - Page 227 SetVideoPage ----------------------------------------------------------------- SetVideoPage ----------------------------------------------------------------- Purpose: Sets the active video page. See the BIOS reference manual for the available video pages. Prototype: void SetVideoPage(int NewPage); Returns: Nothing Parameter: 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); } SCL1 Version 3.1 - Reference Manual - Page 228 SetVideo25 - SetVideo28 - SetVideo4350 ----------------------------------------------------------------- SetVideo25, SetVideo28, SetVideo4350 ----------------------------------------------------------------- Purpose: SetVideo4350 sets the display mode to 43 lines (EGA and VGA display adapters) or to 50 lines (VGA display adapters). SetVideo28 sets the display mode to 28 lines (VGA displays). SetVideo25 resets the display mode to 25 lines. Prototype: void SetVideo25(void); void SetVideo28(void); void SetVideo4350(); 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); } SCL1 Version 3.1 - Reference Manual - Page 229 Shadow ----------------------------------------------------------------- Shadow ----------------------------------------------------------------- Purpose: Draws a shadow to a screen area. Prototype: void Shadow(int Color,int UpperRow,int LeftCol, int LowerRow,int RightCol); Returns: Nothing Parameters: Color - color attribute of the desired shadow effect. A value of "0" will set the shadow effect XOR'ed to the screen area. Use SetShadowColor to specify the shadow color (integer). UpperRow - upper row position of the area (integer). LeftCol - left column position of the area (integer). LowerRow - lower row position of the area (integer). RightCol - right column position of the area (integer). Example: See SetShadowColor #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); } SCL1 Version 3.1 - Reference Manual - Page 230 ShellSort ----------------------------------------------------------------- ShellSort ----------------------------------------------------------------- Purpose: Sort an array using a shell-sort algorithm. It overwrites the unsorted array with the sorted elements. Prototype: int ShellSort(void *base,unsigned int num, unsigned int width, int (*compare)(void *elem1,void *elem2)); Returns: Returns "-1" if there is not enough memory or if the array to sort has only one element. Returns "0" if successful. Parameters: *compare - pointer to a user-supplied function that compares two array elements and returns a value indicating their relationship. ShellSort calls this compare routine and passes pointers to two array elements. For an ascending sorting order the compare function must return "0" if both elements are equal, a positive value (>0) if element1 is greater than element2 or a negative value (<0) if element1 is less than element2. For a descending sorting order the compare function must reverse the "greater than" and "less than" return values. base - pointer to the base of the array to be sorted. SCL1 Version 3.1 - Reference Manual - Page 231 ShellSort num - number of elements to be sorted (unsigned integer). width - size in bytes of each array element (unsigned integer). Example: #include <scl1.h> #include <scl1clor.h> #include <string.h> int compare(void *elem1,void *elem2); typedef struct{ char line[16]; }LINE; LINE lines[]= {"******", "************", "*****", "**************", "*", "*********", "*******", "***********", "*************", "********", "****", "***************", "***", "**********", "**",}; #define LINES sizeof(lines) / sizeof(LINE) main() { Cls(WHITE_BLACK,CLS_ALL); ShellSort(lines,LINES,sizeof(LINE),compare); DrawLines(); } DrawLines() { int i; for(i=0;i < LINES;i++) WriteScreenLen(WHITE_BLACK,i+4,30,sizeof(LINE), (char *)&lines[i]); } SCL1 Version 3.1 - Reference Manual - Page 232 ShellSort - SortPointers int compare(void *elem1,void *elem2) { DrawLines(); WaitTime(10); return(strcmp((char *)elem1,(char *)elem2)); } ----------------------------------------------------------------- SortPointers ----------------------------------------------------------------- Purpose: Sorts, in alphabetical order, a null terminated array of strings. Prototype: void SortPointers(char *p[]); Returns: Nothing Parameter: p - pointer to a null terminated array of char pointers. Example: #include <scl1.h> /* SortPointers demo */ 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]); } SCL1 Version 3.1 - Reference Manual - Page 233 Sound - SoundOff - SoundOn ----------------------------------------------------------------- Sound ----------------------------------------------------------------- Purpose: Sets a sound frequency. Prototype: void Sound(int Freq); Returns: Nothing Parameter: 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. ----------------------------------------------------------------- SoundOff, SoundOn ----------------------------------------------------------------- Purpose: Turns the speaker Off or On. Prototype: void SoundOff(void); void SoundOn(void); Returns: Nothing Parameters: None Example: See Sound SCL1 Version 3.1 - Reference Manual - Page 234 StopWatch ----------------------------------------------------------------- StopWatch ----------------------------------------------------------------- Purpose: Measures elapsed time in 1/100 seconds Prototype: 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. Every time 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); } SCL1 Version 3.1 - Reference Manual - Page 235 TagItem ----------------------------------------------------------------- TagItem ----------------------------------------------------------------- Purpose: Displays one item and permits the user to tag or untag it. Tag or untag an item by pressing the SPACEBAR or by clicking the left mouse button after pointing it. An item that has been tagged will be displayed with a check mark (√) between parenthesis. It can either be used alone or as one of the field types for the Fields2 function. Prototype: 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. It can return a message described in the Messages section. Parameters: Dialog type functions receive messages and structures as parameters. The TagItem parameters must be passed to a structure of the type TIData as follows. typedef struct{ int Color; color for the display of the TagItem. int Row; row where the item is displayed. int Col; column where the item is displayed. int TagFl; 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. char *String; char pointer to the text used to identify the TagItem. unsigned int *ExitKeys; array of keys defined as exit keys. unsigned int EventInfo; structure element that will hold the last key pressed. }TIData; Messages: The following messages can be sent to TagItem: TI_INIT - initialize the TIData structure to NULL and set the following default values: SCL1 Version 3.1 - Reference Manual - Page 236 TagItem Color - set to white characters in a black background or the normal color set by 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. 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. TI_NEW_POSITION - this message is returned when you highlight an item either with the mouse or the keyboard. Example: #include <scl1.h> #include <scl1clor.h> #include <scl1keys.h> unsigned int MyExitKeys[]={ENTER,ESC,0}; TIData ti={WHITE_BLACK,12,28,0,"Create Backup files"}; char Text[]="Use the SPACEBAR to toggle option ON/OFF\n" " Press ENTER to accept, ESC to cancel"; main() { int Mess; Cls(WHITE_BLACK,0,0,24,79); SCL1 Version 3.1 - Reference Manual - Page 237 TagItem - TagList WriteScreen(WHITE_BLACK+HIGHLIGHT,14,20,Text); TagItem(TI_RESET,&ti); ti.ExitKeys=MyExitKeys; TagItem(TI_DRAW,&ti); do { Mess=TagItem(TI_ACTIVE,&ti); }while(Mess != TI_EXIT_KEY); if(ti.EventInfo != ESC) { if(ti.TagFl) WriteScreen(WHITE_BLACK+BLINK+HIGHLIGHT,18,29, "You have selected YES"); else WriteScreen(WHITE_BLACK+BLINK+HIGHLIGHT,18,30, "You have selected NO"); } else WriteScreen(WHITE_BLACK+BLINK+HIGHLIGHT,18,29, "Operation was canceled"); SetCurPos(20,0); exit(0); } ----------------------------------------------------------------- TagList ----------------------------------------------------------------- Purpose: Displays in a ScrollBox any number of items that the user can tag using the keyboard (spacebar) or the mouse. Prototype: 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 is given as an array of structures as follows: struct TagList{ char TagFl; equals "1" if item is tagged. SCL1 Version 3.1 - Reference Manual - Page 238 TagList char *String; pointer to the item string. }; 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. 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. SCL1 Version 3.1 - Reference Manual - Page 239 TagList2 ----------------------------------------------------------------- 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. Prototype: 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: Dialog type functions receive messages and structures as parameters. The Tag List information must be given in a structure type TLData as follows: typedef struct{ int NColor; Color for normal display. int RColor; Color for reversed display). int TColor; Color for displaying a tagged item. int UpperRow; Upper row of the window. int LeftCol; Left column of the window. int LowerRow; Lower row of the window. int RightCol; Right column of the window. char **Array; Pointer to array of pointers to be displayed. char *TagArray; Char pointer to an array that hold the tagging information about each item. }TLData; 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 set by SetDialogColors. SCL1 Version 3.1 - Reference Manual - Page 240 TagList2 RColor - set to highlighted white characters in a black background or the normal color set by SetDialogColors. TColor - set to black characters in a white background or the reversed color set by 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. TL_ACTIVE - browse through the displayed items and permit the selection or tagging of them using the keyboard 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> /* Shows the use of the TagList2 function */ char *options[]={ "Option 1", "Option 2", "Option 3", "Option 4", "Option 5", SCL1 Version 3.1 - Reference Manual - Page 241 TagList2 - TagMenu "Option 6", "Option 7", 0}; char tarray[7]; main() { TLData tl; int i,Mess; TagList2(TL_INIT,&tl); /* initialize structure */ tl.UpperRow=6; /* modify position */ tl.LowerRow=15; tl.LeftCol=20; tl.RightCol=60; tl.Array=options; /* our data*/ tl.TagArray=tarray; /* tag array */ TagList2(TL_DRAW,&tl); /* draw */ InitMouse(IM_SHOW); 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"); } ----------------------------------------------------------------- TagMenu ----------------------------------------------------------------- Purpose: Displays a menu from which you can tag 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. Upon exit you can either cancel the operation or continue. Prototype: int TagMenu(char NormalColor, char ReverseColor, char HighlightColor, char NumOpt,struct MenuOpt*, int XMin,int XMax,int YMin,int YMax); SCL1 Version 3.1 - Reference Manual - Page 242 TagMenu Returns: The returned value is "0" if the user selects the accept option and "-1" if the operation is canceled. 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 is given as an array of structures as follows: struct MenuOpt{ int Row; Row position for the menu item. int Col; Column position for the menu item. char *String; Pointer to the menu item text. int Letter; Letter to be highlighted for fast keyboard selection of the menu item. }; 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 of the menu background and foreground (integer). RColor - color of the highlighted item menu bar (integer). HColor - color 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). SCL1 Version 3.1 - Reference Manual - Page 243 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"); } SCL1 Version 3.1 - Reference Manual - Page 244 TextWindow ----------------------------------------------------------------- TextWindow ----------------------------------------------------------------- Purpose: Displays text in a window. Prototype: int TextWindow(int Message,TWData *p,...); Returns: This is a dialog type function. See Appendix "E" for a description of the general operation of these functions. Returns a message described in the Messages section. Parameters: Dialog type functions receive messages and structures as parameters. The text window information is given in a structure type TWData as follows: typedef struct{ int Color; Color for the window display. int UpperRow; Upper row for the window display. int LeftCol; Left column for the window display. int LowerRow; Lower row for the window display. int RightCol; Right column for the window display. int FrameType; Frame type as defined in Box. int 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. int Position; Structure element (internal) to determine the current position within the window. }TWData; The following messages can be sent to TextWindow: SCL1 Version 3.1 - Reference Manual - Page 245 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 set by SetDialogColors. LowerRow - set to maximum screen row size. RightCol - set to maximum screen column size. 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. 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> /* TextWindow example */ char *strings[]={ "These strings will be written", "to a Text Window, one by one.", "Text will scroll in TTY mode", SCL1 Version 3.1 - Reference Manual - Page 246 TextWindow "So as to simulate a", "DOS like screen.", "Several control characters", "like\t\ttab (\\t),", "new line (\\n)\rand carriage return (\\r)", "are supported."}; main() { TWData twd; int i,Mess; Cls(WHITE_BLACK,CLS_ALL); TextWindow(TW_INIT,&twd); /* initialize structure */ twd.UpperRow=10; /* modify position */ twd.LowerRow=15; 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 < 9;++i) { Mess=TextWindow(TW_WRITE,&twd,strings[i]); if(Mess==TW_WINDOW_FULL) /* window full? */ { WriteScreen(WHITE_BLACK+HIGHLIGHT,16,21,"Press any key for more..."); GetKey(); TextWindow(TW_CLS,&twd); } } WaitTime(100); /* 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 < 9;++i) TextWindow(TW_WRITE,&twd,strings[i]); } SCL1 Version 3.1 - Reference Manual - Page 247 TL_SetUserLang - TrapBIOSScreenWrite - TrapInt10 - RestoreInt10 ----------------------------------------------------------------- TL_SetUserLang ----------------------------------------------------------------- Purpose: Lets you modify the default prompts of the TagList2 function. With this function you can customize the default "Ok" and "Cancel" prompts. This is useful when writing programs in languages other that English. Prototype: void TL_SetUserLang(char **prompt,int offset1, int offset2); Returns: Nothing. Parameters: prompt - pointer to a null terminated array of char pointers that holds the modified prompts. offset1 - distance from the left margin of the box where the first mouse button ("Ok") will be displayed. offset2 - distance from the left margin of the box where the second mouse button ("CANCEL") will be displayed. Example: See FB_SetUserLang ----------------------------------------------------------------- TrapBIOSScreenWrite, TrapInt10, RestoreInt10 ----------------------------------------------------------------- Purpose: Traps BIOS interrupt 0x10 and prevents BIOS from writing to the screen. Upon program exit the original interrupt is restored. You can also call the TrapInt10 and RestoreInt10 functions to get the same results. Prototype: int TrapBIOSScreenWrite(void); void TrapInt10(void); void RestoreInt10(void); Returns: TrapBIOSScreenWrite returns "-1" if an error is encountered. Parameters: None SCL1 Version 3.1 - Reference Manual - Page 248 TrapBIOSScreenWrite - TrapInt10 - RestoreInt10 - TrapInt23 Example: one step procedure: TrapBIOSScreenWrite(); /* BIOS and DOS screen write trapped*/ /* int 0x10 will be restored automatically on exit */ or two step procedure: TrapInt10(); /* trap int 0x10 */ . . . . RestoreInt10(); /* restore it */ ----------------------------------------------------------------- TrapInt23 ----------------------------------------------------------------- Purpose: Traps every occurrence of the Control+Break key combination. Global variable I23_CtrlBreakFl is incremented every time this key combination is pressed. Prototype: 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); } SCL1 Version 3.1 - Reference Manual - Page 249 TrapInt24 ----------------------------------------------------------------- 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. To alter the error box appearance use SetInt24Colors, Int24ShadowOff and Int24ShadowOn. 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. Prototype: void TrapInt24(void); Returns: Nothing Parameters: None SCL1 Version 3.1 - Reference Manual - Page 250 Tsound - Video ----------------------------------------------------------------- TSound ----------------------------------------------------------------- Purpose: Plays a sound of the specified frequency and for a specified length of time (in hundredths of a second). Prototype: 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: TSound(1000,100);/*play a 1000 Hertz tone for one second.*/ See the note definitions in header file SCL1SND.H. ----------------------------------------------------------------- Video ----------------------------------------------------------------- Purpose: Detects if the video adapter in use is either Monochrome or Color. Declares and defines the variable VC_Segment (unsigned int) that holds Video Buffer segment address. (The VideoConfig function provides additional information) Prototype: unsigned int Video(void); Returns: The return value is defined in SCL1.H as MONO for monochrome monitors, or COLOR if a color monitors. 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"); } SCL1 Version 3.1 - Reference Manual - Page 251 VideoConfig ----------------------------------------------------------------- VideoConfig ----------------------------------------------------------------- Purpose: Fills a structure with the current video information for use by other functions. It 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. Prototype: struct VideoData *VideoConfig(void); Returns: a pointer to the VideoData structure. Parameters: The video information is stored in a structure type VideoData as follows: struct VideoData{ int Monitor; Type of monitor detected. The following types have been defined 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 int Mode; Active video mode. int Page; Active video page. int Lines; Number of rows in active video mode. int Cols; Number of columns in active video mode. unsigned int Segment; Segment used by current video mode. SCL1 Version 3.1 - Reference Manual - Page 252 VideoConfig int Retrace; Structure element that tells the functions to use or not to use retrace. With a "0" value the direct screen writes will use no retrace, with a "1" value will use retrace. By default this value will be set to "0" for 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. SCL1 Version 3.1 - Reference Manual - Page 253 WaitKeyMouse - WaitTime - Window ----------------------------------------------------------------- WaitKeyMouse ----------------------------------------------------------------- Purpose: Waits for a keystroke or pressing of the left mouse button. The function clears the keyboard buffer on entry. Prototype: unsigned int WaitKeyMouse(void); Returns: the key's Scan/Ascii code if a key is pressed. Parameters: None Example: See HideMouse ----------------------------------------------------------------- WaitTime ----------------------------------------------------------------- Purpose: Sets a delay of X hundredths of a second. Prototype: void WaitTime(unsigned int HSec); Returns: Nothing Parameter: HSec - time interval in hundredths of a second. ----------------------------------------------------------------- Window ----------------------------------------------------------------- Purpose: Saves, clears and restores a window. Prototype: void Window(int Color,int UpperRow,int LeftCol, int LowerRow,int RightCol,char* Flag, char* Buffer); Returns: Nothing Parameters: Color - color for the area to be cleared (integer). UpperRow - upper left row position of the area (integer). LeftCol - upper left column position of the area (integer). LowerRow - lower right row position of the area (integer). SCL1 Version 3.1 - Reference Manual - Page 254 Window RightCol - lower right column position 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. Notes: 1. Flag is toggled automatically every time the function is called. 2. The buffer size is the number of characters * 2. This size can be calculated by using the W_BUF_SIZE macro defined in SCL1.H. 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..."); SCL1 Version 3.1 - Reference Manual - Page 255 Window - WriteChar 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); } ----------------------------------------------------------------- WriteChar ----------------------------------------------------------------- Purpose: Writes a character directly to the screen buffer a specified number of times. Prototype: void WriteChar(int Color,int Row,int Col,int Count, int Character); Returns: Nothing Parameters: Color - color for the character to be displayed (integer). Row - row position to start display (integer). Col - column position to start display (integer). Count - number of times the character is written (integer). Character - the character to be displayed (integer). Example: Writes 80 dashes to the screen from line 10, column 0, using black characters in a white background. WriteChar(0x70,10,0,80,'-'); SCL1 Version 3.1 - Reference Manual - Page 256 WriteFile - WriteOffLen ----------------------------------------------------------------- WriteFile ----------------------------------------------------------------- Purpose: Writes to a file. The function can also be used to write to the standard printer, console or any other device if the proper handle number is specified. Prototype: int WriteFile(int Handle,char *Buffer, unsigned int Bytes); Returns: The DOS error code or "0" if no error occurs. (See Appendix "A", FILE FUNCTIONS, for more information). Parameters: Handle - handle given by DOS when you open or create a file. Buffer - pointer to the buffer that will hold the data. Bytes - number of bytes to write (unsigned integer). Example: See CloseFile ----------------------------------------------------------------- WriteOffLen ----------------------------------------------------------------- Purpose: Writes a string directly to the video buffer. The display position is specified as an offset from the home position. The length to display is specified. If the string is shorter than the specified length, the remaining spaces are filled with spaces. Prototype: void WriteOffLen(int Color,int Offset,int Count, char * String); Returns: Nothing Parameters: Color - color 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. SCL1 Version 3.1 - Reference Manual - Page 257 WriteOffLen - WriteOffset Example: Display a 15 character string in position offset 1500, using white characters in a black background. WriteOffLen(0x7,1500,15,"This is a test. "); ----------------------------------------------------------------- WriteOffset ----------------------------------------------------------------- Purpose: Writes a character directly to the video buffer. The display position is specified as an offset from the home position. Prototype: void WriteOffset(int Color,int Offset,int Character); Returns: Nothing Parameters: Color - color 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]); } SCL1 Version 3.1 - Reference Manual - Page 258 WriteScreen - WriteScreenC - WriteScreenR ----------------------------------------------------------------- WriteScreen, WriteScreenC, WriteScreenR ----------------------------------------------------------------- Purpose: Writes a string directly to the video buffer. WriteScreen left justifies, WriteScreenC centers and WriteScreenR right justifies the string. Supports control character "\n". Prototype: void WriteScreen(int Color,int Row,int Col, char *String); void WriteScreenC(int Color,int Row,int Col, char *String); void WriteScreenR(int Color,int Row,int Col, char *String); Returns: Nothing Parameters: Color - color of the desired display (integer). Row - row position where to display the string (integer). Col - column position where to display the string (integer). String - 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..."; main() { /* Displays the string Mess left justified in row 4, column 20 */ WriteScreen(WHITE_BLACK,4,20,Mess); GetKey(); SCL1 Version 3.1 - Reference Manual - Page 259 WriteScreen - WriteScreenC - WriteScreenR - WriteScreenCLen WriteScreenLen - WriteScreenRLen /* Displays the string Mess right justified in row 4, column 20*/ WriteScreenR(WHITE_BLACK,4,20,Mess); GetKey(); /* Displays the string Mess centered around row 10, column 40 */ WriteScreenC(WHITE_BLACK,10,40,Mess); } ----------------------------------------------------------------- WriteScreenCLen, WriteScreenLen, WriteScreenRLen ----------------------------------------------------------------- Purpose: Writes a string to the video buffer. The length to display is specified. WriteScreenCLen will center, WriteScreenLen will left justify and WriteScreenRLen will right justify the text. If the string is shorter than the specified length, the remaining spaces are filled with spaces. Prototype: void WriteScreenCLen(int Color,int Row,int Col, int Count,char *String); void WriteScreenLen(int Color,int Row,int Col, int Count,char *String); void WriteScreenRLen(int Color,int Row,int Col, int Count,char *String); Returns: Nothing Parameters: Color - color of the desired display (integer). Row - row position where to display the string (integer). Col - column position where to display the string (integer). Count - length to display (integer). String - pointer to the string to be displayed. SCL1 Version 3.1 - Reference Manual - Page 260 WriteScreenCLen - WriteScreenLen - WriteScreenRLen 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\n is shorter than the length specified:"; char *strings[]={"1234567890","12345678","12345"}; 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(); } } SCL1 Version 3.1 - Reference Manual - Page 261 WriteWindow ----------------------------------------------------------------- WriteWindow ----------------------------------------------------------------- Purpose: Writes a string to a previously created window. The string length to display is specified. If the string is shorter than the specified length, the remaining spaces are filled with spaces. You can specify the justification method. Before using this function make sure the WData structure has been initialized and the window created. Prototype: void WriteWindow(WData *wd,int Row,int Col, int Count,int Justification,char *String); Returns: Nothing Parameters: WData - the address of the WData structure. Row - row position, relative to the defined window, to start the string display (integer). This upper left corner of the window has 0,0 coordinates. Col - column position, relative to the defined window, to start the string display (integer). Count - string length to display (integer). If the specified screen length is larger than the string's length the rest of the line will be cleared. Justification - defines the way the text will be written to the window. The following justification options have been defined in SCL1.H: W_LEFT - text will be left justified. W_RIGHT - text will be right justified. W_CENTER - text will be centered around specified coordinates, and NOT around window. If you want to specify the window's center you can use the WData's HorCenter element. String - pointer to the string to be displayed. Example: See InitWData SCL1 Version 3.1 - Reference Manual - Page 262 XMS_AllocExtended ----------------------------------------------------------------- XMS_AllocExtended ----------------------------------------------------------------- Purpose: Attempts to allocate a block of the given size out of the pool of free extended memory. If a block is available, it is reserved for the caller and a handle to that block is returned to be used in all subsequent extended memory calls. Prototype: int XMS_AllocExtended(int *handle, unsigned int kbytes); Returns: Returns one of the following messages defined in header file SCL1XMS.H: XMS_OK if the block is allocated. XMS_NOT_IMPLEMENTED if the function is not implemented. XMS_VDISK_PRESENT if a VDISK device is detected. XMS_ALL_EXTENDED_ALLOCATED if all extended memory is allocated. XMS_NO_MORE_HANDLES if all available extended memory handles are in use. Parameters: handle - pointer to an unsigned integer value that will hold a 16-bit handle to the allocated block. kbytes - pointer to an unsigned integer value that holds the amount of extended memory being requested in K-bytes. Example: See XMS_Init SCL1 Version 3.1 - Reference Manual - Page 263 XMS_FreeExtended ----------------------------------------------------------------- XMS_FreeExtended ----------------------------------------------------------------- Purpose: Frees a block of extended memory which was previously allocated using the XMS_AllocExtended function. Programs which allocate extended memory should free their memory blocks before exiting. Prototype: int XMS_FreeExtended(int handle); Returns: Returns one of the following messages defined in header file SCL1XMS.H: XMS_OK if the block is successfully freed. XMS_NOT_IMPLEMENTED if the function is not implemented. XMS_VDISK_PRESENT if a VDISK device is detected. XMS_INVALID_HANDLE if the handle is invalid. XMS_BLOCK_LOCKED if the handle is locked. Parameter: handle - unsigned integer value that holds a 16-bit handle to the allocated block. Example: See XMS_Init SCL1 Version 3.1 - Reference Manual - Page 264 XMS_GetEMBHandleInfo ----------------------------------------------------------------- XMS_GetEMBHandleInfo ----------------------------------------------------------------- Purpose: Returns additional information about an extended memory block. Use XMS_LockExtended to get the block's base address. Prototype: int XMS_GetEMBHandleInfo(int handle,int *LockCount, int *FreeHandles,int *BlockSize); Returns: Returns one of the following messages defined in header file SCL1XMS.H: XMS_OK if the block's information is found. XMS_VDISK_PRESENT if a VDISK device is detected. XMS_NOT_IMPLEMENTED if the function is not implemented. XMS_INVALID_HANDLE if the handle is invalid. Parameters: handle - unsigned integer value that holds a handle to the extended memory block. LockCount - pointer to an integer value that will hold the block's lock count. FreeHandles - pointer to an integer value that will hold the number of free EMB handles in the system. BlockSize - pointer to an integer value that will hold the block's length in K-bytes. Example: See XMS_Init SCL1 Version 3.1 - Reference Manual - Page 265 XMS_GetVersion ----------------------------------------------------------------- XMS_GetVersion ----------------------------------------------------------------- Purpose: Lets you obtain the version of the Extended Memory Manager (driver) installed in your system. Prototype: int XMS_GetVersion(unsigned int *version); Returns: Returns one of the following messages defined in header file SCL1XMS.H: XMS_OK if XMS has been initialized. Parameter: version - pointer to an unsigned integer value that contains the XMS driver's version number. To determine the version number you can decode the returned value as follows: Two macros XMS_MAJOR_VER(i) and XMS_MINOR_VER(i) have been defined int SCL1XMS.H. These macros extract the XMS version number from the variable version. To get the most significant part (MAJOR) of the version number use the following relation: Major=XMS_MAJOR_VER(i); The get the least significant part (MINOR) of the version number use the following relation: Minor=XMS_MINOR_VER(i); The XMS driver version number will be: Version Number = Major.Minor Example: See XMS_Init SCL1 Version 3.1 - Reference Manual - Page 266 XMS_GlobalDisableA20, XMS_GlobalEnableA20 ----------------------------------------------------------------- XMS_GlobalDisableA20 ----------------------------------------------------------------- Purpose: Disable the A20 line. It should only be used by programs which have control of the HMA. Prototype: int XMS_GlobalDisableA20(void); Returns: Returns one of the following messages defined in header file SCL1XMS.H: XMS_OK if HMA if the A20 is disabled. XMS_NOT_IMPLEMENTED if function is not implemented. XMS_VDISK_PRESENT if a VDISK device is detected. XMS_A20_ERROR if an A20 error occurs. XMS_A20_ALREADY_ENABLED if the A20 line is enabled. Parameters: None Example: See XMS_Init ----------------------------------------------------------------- XMS_GlobalEnableA20 ----------------------------------------------------------------- Purpose: Enable the A20 line. It should only be used by programs which have control of the HMA. The A20 line should be turned off before a program releases control of the system. Prototype: int XMS_GlobalEnableA20(void); Returns: Returns one of the following messages defined in header file SCL1XMS.H: XMS_OK if HMA if the A20 is enabled. XMS_NOT_IMPLEMENTED if function is not implemented. XMS_VDISK_PRESENT if a VDISK device is detected. XMS_A20_ERROR if an A20 error occurs. Parameters: None Example: See XMS_Init SCL1 Version 3.1 - Reference Manual - Page 267 XMS_Init ----------------------------------------------------------------- XMS_Init ----------------------------------------------------------------- Purpose: Initialize the Extended Memory Management functions. Determine if a valid Extended Memory Manager (driver) has been installed in your system. Prototype: int XMS_Init(void); Returns: Returns one of the following messages defined in header file SCL1XMS.H: XMS_OK if XMS has been initialized. Parameters: None Example: #include <scl1xms.h> #include <memory.h> #include <dos.h> /* eXtended (XMS) Memory functions */ void Pause(void); void PrintA20Status(void); void PrintError(unsigned int Error); void PrintHandleInfo(int handle); typedef struct{ unsigned int ErrorCode; char *ErrorMess; }XMSERRORS; XMSERRORS xmse[]= { XMS_NOT_IMPLEMENTED ,"XMS function not available", XMS_VDISK_PRESENT ,"Virtual Disk present", XMS_A20_ERROR ,"A20 line error", XMS_GENERAL_DRIVER_ERROR ,"General XMS driver error", XMS_UNRECOVERABLE_ERROR ,"Unrecoverable error", XMS_HMA_NOT_EXIST ,"HMA does not exist", XMS_HMA_IN_USE ,"HMA already in use", XMS_HMA_NOT_ALLOCATED ,"HMA is not allocated", XMS_A20_ALREADY_ENABLED ,"A20 is already enabled", XMS_ALL_EXTENDED_ALLOCATED,"All XMS memory allocated", XMS_NO_MORE_HANDLES ,"No more handles available", XMS_INVALID_HANDLE ,"Invalid handle number", XMS_INVALID_SOURCE_HANDLE ,"Invalid source handle", XMS_INVALID_SOURCE_OFFSET ,"Invalid source offset", SCL1 Version 3.1 - Reference Manual - Page 268 XMS_Init XMS_INVALID_DEST_HANDLE ,"Invalid destination handle", XMS_INVALID_DEST_OFFSET ,"Invalid destination offset", XMS_INVALID_LENGTH ,"Invalid length", XMS_INVALID_OVERLAP ,"Invalid overlap", XMS_PARITY_ERROR ,"Parity error", XMS_BLOCK_NOT_LOCKED ,"Block not locked", XMS_BLOCK_LOCKED ,"Block locked", XMS_LOCK_COUNT_OVERFLOW ,"Lock count overflow", XMS_LOCK_FAIL ,"Lock fail", XMS_UMB_SMALL_AVAILABLE ,"Smaller UMB available", XMS_UMB_NOT_AVAILABLE ,"UMB not available", XMS_UMB_INVALID_SEGMENT ,"Invalid segment", }; char CompOkStr[]="\tCompare OK\n"; char CompErrStr[]="\tCompare ERROR\n"; /* struct used to move or copy data from extended memory */ XMSMove xmove; char TestData[80]="This string will be used to test XMS functions"; main() { unsigned int available,total,i,handle; char buffer[sizeof(TestData)]; void far *p; /* initialize, check if XMS driver is present */ if(XMS_Init() != XMS_OK) { printf("No XMS available\n"); exit(-1); } else printf("\n\nSCL1 Version 3.1 eXtended (XMS) Memory Test\n"); XMS_GetVersion(&i); /* get version number */ /* add 0x30 to returned value to get ASCII code */ memset(buffer,0,sizeof(buffer)); buffer[0]=XMS_MAJOR_VER(i) + 0x30; buffer[1]='.'; buffer[2]=XMS_MINOR_VER(i) + 0x30; printf("XMS Version %s\n\n",buffer); SCL1 Version 3.1 - Reference Manual - Page 269 XMS_Init /* High Memory Area Test */ printf("High Memory Area (HMA) Test\n"); if((i=XMS_RequestHMA())==XMS_OK) { /* allocated OK */ printf("\tHMA allocated...\n"); /* enable the A20 line so that we can access HMA */ if((i=XMS_GlobalEnableA20())==XMS_OK) { _fmemcpy(XMS_HMA,(void far *)TestData,sizeof(TestData)); printf("\tData copied to HMA...\n"); /* copy HMA to local buffer */ memset(buffer,0,sizeof(buffer)); _fmemcpy((void far *)buffer,XMS_HMA,sizeof(buffer)); if(memcmp(buffer,TestData,sizeof(TestData))==0) printf(CompOkStr); else printf(CompErrStr); } else printf("\tError enabling A20 line, cannot access HMA\n"); /* free HMA */ XMS_ReleaseHMA(); printf("\tReleasing HMA...\n"); } else PrintError(i); Pause(); /* Extended Memory Test */ printf("Extended Memory Test\n"); SCL1 Version 3.1 - Reference Manual - Page 270 XMS_Init if((i=XMS_QueryFreeExtended(&available,&total))==XMS_OK && available > 0) { printf("\tLargest available block: %u KB\n",available); printf("\tTotal available memory: %u KB\n",total); /* allocate all memory */ if((i=XMS_AllocExtended(&handle,available))==XMS_OK) { printf("\tSuccesful allocation of %u KB...\n",available); printf("\tCopying data to allocated memory...\n"); /* copy TestData buffer to extended memory */ xmove.bytes=(unsigned long)sizeof(TestData); xmove.shandle=0; xmove.source=(void far *)TestData; xmove.dhandle=handle; xmove.destination=0; if((i=XMS_MoveExtended(&xmove))==XMS_OK) { /* copy extended memory to local buffer */ memset(buffer,0,sizeof(buffer)); xmove.bytes=sizeof(TestData); xmove.shandle=handle; xmove.source=0; xmove.dhandle=0; xmove.destination=(void far *)buffer; if((i=XMS_MoveExtended(&xmove))==XMS_OK) { if(memcmp(TestData,buffer,sizeof(TestData))==0) printf(CompOkStr); else printf(CompErrStr); } else PrintError(i); } else PrintError(i); /* get handle information */ PrintHandleInfo(handle); Pause(); SCL1 Version 3.1 - Reference Manual - Page 271 XMS_Init /* Lock/Unlock Test */ printf("Lock/Unlock Test\n\tLocking allocated memory...\n"); if((i=XMS_LockExtended(handle,&p))==XMS_OK) { printf("\tLocked block 32-bit linear address: %lX\n",p); PrintHandleInfo(handle); printf("\tUnlocking allocated memory...\n"); XMS_UnlockExtended(handle); PrintHandleInfo(handle); } else PrintError(i); /* Reallocating Test */ Pause(); printf("Reallocating Test\n"); /* reallocate buffer to 1kb */ if((i=XMS_ReallocExtended(handle,1))==XMS_OK) { printf("\tBlock reallocated to 1 KB\n"); /* get handle info */ PrintHandleInfo(handle); } else printf("\tError reallocating\n"); /* free memory */ XMS_FreeExtended(handle); printf("\tReleasing Extended memory...\n"); } else printf("\tError Allocating\n"); } Pause(); /* A20 Line Test */ printf("A20 Line Test\n"); PrintA20Status(); SCL1 Version 3.1 - Reference Manual - Page 272 XMS_Init if((i=XMS_LocalEnableA20())==XMS_OK) { printf("\tLocally enabling A20 line...\n"); XMS_LocalEnableA20(); PrintA20Status(); printf("\tLocally disabling A20 line...\n"); XMS_LocalDisableA20(); PrintA20Status(); } else PrintError(i); Pause(); /* Upper Memory Blocks Test */ printf("Upper Memory Block (UMB) Test\n"); /* By requesting 0xffff paragraphs, the largest available block size will be reported if UMB blocks are available*/ if((i=XMS_RequestUMB(0xffff,&p,&available))==XMS_OK || i==XMS_UMB_SMALL_AVAILABLE) { printf("\tUMB available, allocating largest block available...\n"); if(i==XMS_UMB_SMALL_AVAILABLE) { if((i=XMS_RequestUMB(available,&p,&available))!=XMS_OK) PrintError(i); else { printf("\tUMB Size: %li bytes\n\tUMB Address: %X\n", (long) available * 16L,FP_SEG(p)); printf("\tCopying data to allocated memory...\n"); _fmemcpy(p,(void far *)TestData,sizeof(TestData)); memset(buffer,0,sizeof(buffer)); _fmemcpy((void far *)buffer,p,sizeof(TestData)); if(memcmp(buffer,TestData,sizeof(TestData))==0) printf(CompOkStr); else printf(CompErrStr); printf("\tReleasing UMB...\n"); XMS_ReleaseUMB(p); } } } else PrintError(i); } SCL1 Version 3.1 - Reference Manual - Page 273 XMS_Init void PrintError(unsigned int Error) { int i; for(i=0;i < sizeof(xmse) /sizeof(XMSERRORS);++i) { if(xmse[i].ErrorCode==Error) { printf("\t%s\n",xmse[i].ErrorMess); return; } } printf("\tUnknown error #%X\n",Error); } void Pause(void) { printf("-- more --"); GetKey(); printf("\r \n"); } void PrintHandleInfo(int handle) { int lcount,fhandle,bsize; XMS_GetEMBHandleInfo(handle,&lcount,&fhandle,&bsize); printf("\tHandle Report:\n"); printf("\t\tFree Handles: %i\n",fhandle); printf("\t\tAllocated Block Lock Count: %i\n",lcount); printf("\t\tAllocated Block Size: %i KB\n",bsize); } void PrintA20Status(void) { unsigned int i; int j; if((j=XMS_QueryA20(&i))==XMS_OK) { if(i==XMS_A20_ENABLED) printf("\tA20 enabled\n"); else printf("\tA20 NOT enabled\n"); } else PrintError(j); } SCL1 Version 3.1 - Reference Manual - Page 274 XMS_LocalDisableA20, XMS_LocalEnableA20 ----------------------------------------------------------------- XMS_LocalDisableA20 ----------------------------------------------------------------- Purpose: Cancels a previous call to the XMS_LocalEnableA20 function. It should only be used by programs which need direct access to extended memory. Prototype: int XMS_LocalDisableA20(void); Returns: Returns one of the following messages defined in header file SCL1XMS.H: XMS_OK if HMA if the A20 is disabled. XMS_NOT_IMPLEMENTED if function is not implemented. XMS_VDISK_PRESENT if a VDISK device is detected. XMS_A20_ERROR if an A20 error occurs. XMS_A20_ALREADY_ENABLED if the A20 line is enabled. Parameters: None ----------------------------------------------------------------- XMS_LocalEnableA20 ----------------------------------------------------------------- Purpose: Enables the A20 line. It should only be used by programs which need direct access to extended memory. Programs which use this function should disable the A20 line before releasing control of the system. Prototype: int XMS_LocalEnableA20(void); Returns: Returns one of the following messages defined in header file SCL1XMS.H: XMS_OK if HMA if the A20 is enabled. XMS_NOT_IMPLEMENTED if function is not implemented. XMS_VDISK_PRESENT if a VDISK device is detected. XMS_A20_ERROR if an A20 error occurs. Parameters: None Example: See XMS_Init SCL1 Version 3.1 - Reference Manual - Page 275 XMS_LockExtended ----------------------------------------------------------------- XMS_LockExtended ----------------------------------------------------------------- Purpose: Locks an extended memory block and returns its base address. Locked memory blocks are guaranteed not to move. The 32-bit pointer is only valid while the block is locked. Locked blocks should be unlocked as soon as possible. A block does not have to be locked before using XMS_MoveExtended function. Prototype: int XMS_LockExtended(int handle,void far **bpt); Returns: Returns one of the following messages defined in header file SCL1XMS.H: XMS_OK if the block is locked. XMS_NOT_IMPLEMENTED if the function is not implemented. XMS_VDISK_PRESENT if a VDISK device is detected. XMS_INVALID_HANDLE if the handle is invalid. XMS_LOCK_COUNT_OVERFLOW if the block's lock count overflows. XMS_LOCK_FAIL if the lock fails. Parameters: handle - an unsigned integer value that holds a 16-bit handle to the allocated block. bpt - pointer to a far pointer that will hold the 32 bit address of the memory block. Example: See XMS_Init SCL1 Version 3.1 - Reference Manual - Page 276 XMS_MoveExtended ----------------------------------------------------------------- XMS_MoveExtended ----------------------------------------------------------------- Purpose: Transfers a block of data from one location to another. It is primarily used for moving blocks of data between conventional memory and extended memory, however it can be used for moving blocks within conventional memory and within extended memory. Prototype: int XMS_MoveExtended(XMSMove *); Returns: Returns one of the following messages defined in header file SCL1XMS.H: XMS_OK if the move is successful. XMS_NOT_IMPLEMENTED if function is not implemented. XMS_VDISK_PRESENT if a VDISK device is detected. XMS_INVALID_SOURCE_HANDLE if shandle is invalid. XMS_INVALID_SOURCE_OFFSET if the Source Offset (*source)is invalid. XMS_INVALID_DEST_HANDLE if dhandle is invalid. XMS_INVALID_DEST_OFFSET if the Destination Offset (*destination) is invalid. XMS_INVALID_LENGTH if the length (bytes) is invalid, must me a pair number. XMS_INVALID_OVERLAP if the move has an invalid overlap. XMS_PARITY_ERROR if a parity error occurs. XMS_A20_ERROR if an A20 error occurs. Parameters: The function receives a pointer to a XMSMove type structure as follows: typedef struct{ unsigned long bytes; Number of bytes to transfer. unsigned int shandle; Handle of source block. This value will be "0" if the source block belongs to conventional memory. SCL1 Version 3.1 - Reference Manual - Page 277 XMS_MoveExtended, XMS_QueryA20 void far *source; If shandle is set to "0", this pointer is a standard segment:offset pair to memory that is directly accessible by the processor. If shandle is not "0" this variable is a 32 bit offset to extended memory block. unsigned int dhandle; Handle of destination block. This value will be "0" if the source block belongs to conventional memory. void far *destination; If dhandle is set to "0", this pointer is a standard segment:offset pair to memory that is directly accessible by the processor. If dhandle is not "0" this variable is a 32 bit offset to extended memory block. }XMSMove; Example: See XMS_Init ----------------------------------------------------------------- XMS_QueryA20 ----------------------------------------------------------------- Purpose: This function checks to see if the A20 line is physically enabled. It does this in a hardware independent manner by seeing if "memory wrap" occurs. Prototype: int XMS_QueryA20(int *A20status); Returns: Returns one of the following messages defined in header file SCL1XMS.H: XMS_A20_NOT_ENABLED message if the A20 line is not physically enabled. XMS_A20_ENABLED message if the A20 line is enabled. XMS_NOT_IMPLEMENTED if function is not implemented. XMS_VDISK_PRESENT if a VDISK device is detected. Parameter: A20status - pointer to an integer value that will hold the A20 line status. It is used to return this status to the calling program. Example: See XMS_Init SCL1 Version 3.1 - Reference Manual - Page 278 XMS_QueryFreeExtended, XMS_ReallocExtended ----------------------------------------------------------------- XMS_QueryFreeExtended ----------------------------------------------------------------- Purpose: Returns the size of the largest available extended memory block in the system. The HMA is not included in the returned value even if it is not in use. Prototype: int XMS_QueryFreeExtended (unsigned int *FreeKB, unsigned int *TotalKB); Returns: Returns one of the following messages defined in header file SCL1XMS.H: XMS_NOT_IMPLEMENTED if function is not implemented. XMS_VDISK_PRESENT if a VDISK device is detected. XMS_ALL_EXTENDED_ALLOCATED if all extended memory is allocated. Parameters: FreeKB - pointer to an unsigned integer that will hold the size of the largest free extended memory block in K-bytes. TotalKB - pointer to an unsigned integer value that will hold total amount of free extended memory in K-bytes. Example: See XMS_Init ----------------------------------------------------------------- XMS_ReallocExtended ----------------------------------------------------------------- Purpose: Attempts to reallocate an unlocked extended memory block so that it becomes the newly specified size. Prototype: int XMS_ReallocExtended(int handle, unsigned int newsize); Returns: Returns one of the following messages defined in header file SCL1XMS.H: XMS_OK if the block is reallocated. XMS_VDISK_PRESENT if a VDISK device is detected. XMS_NOT_IMPLEMENTED if function is not implemented. XMS_INVALID_HANDLE if the handle is invalid. SCL1 Version 3.1 - Reference Manual - Page 279 XMS_ReallocExtended - XMS_ReleaseHMA - XMS_RequestHMA XMS_BLOCK_LOCKED if the block is not locked XMS_ALL_EXTENDED_ALLOCATED if all available extended memory is allocated. XMS_NO_MORE_HANDLES if all available extended memory handles are in use. Parameters: handle - unsigned integer value that holds a handle to the unlocked extended memory block to reallocate. newsize - pointer to an unsigned integer value that holds the new size for the extended memory block in K-bytes. Example: See XMS_Init ----------------------------------------------------------------- XMS_ReleaseHMA, XMS_RequestHMA ----------------------------------------------------------------- Purpose: These functions attempt to reserve and release the 64K-16 byte high memory area (HMA) to allow other programs to use it. Programs which allocate the HMA must release it before exiting. Prototype: int XMS_ReleaseHMA(void); int XMS_RequestHMA(void); Returns: Returns one of the following messages defined in header file SCL1XMS.H: XMS_OK if HMA if the HMA is successfully assigned (XMS_RequestHMA) or released (XMS_ReleaseHMA). XMS_NOT_IMPLEMENTED if function is not implemented. XMS_VDISK_PRESENT if a VDISK device is detected. XMS_HMA_NOT_EXIST if the HMA does not exist. XMS_HMA_NOT_ALLOCATED if the HMA was not allocated. XMS_HMA_IN_USE is already in use. Parameters: None Example: See XMS_Init SCL1 Version 3.1 - Reference Manual - Page 280 XMS_ReleaseUMB - XMS_RequestUMB ----------------------------------------------------------------- XMS_ReleaseUMB ----------------------------------------------------------------- Purpose: Frees a previously allocated Upper Memory Block (UMB). When an UMB has been released, any code or data stored in it becomes invalid and should not be accessed. Prototype: int XMS_ReleaseUMB(void far *UMBpt); Returns: Returns one of the following messages defined in header file SCL1XMS.H: XMS_OK if the block was released. XMS_NOT_IMPLEMENTED if the function is not implemented. XMS_UMB_INVALID_SEGMENT if the UMB segment number is invalid. Parameter: UMBpt - far pointer to the segment number of the upper memory block. Example: See XMS_Init ----------------------------------------------------------------- XMS_RequestUMB ----------------------------------------------------------------- Purpose: Attempts to allocate an Upper Memory Block (UMB). If the function fails, the size of the largest free UMB is returned. UMBs are located below the 1MB address boundary. The A20 Line does not need to be enabled before accessing an allocated UMB. UMBs are paragraph aligned. To determine the size of the largest available UMB, attempt to allocate one with a size of FFFFh. Prototype: int XMS_RequestUMB(unsigned int para, void far **UMBpt,unsigned int *ActualSize); Returns: Returns one of the following messages defined in header file SCL1XMS.H: XMS_OK if the request is granted. XMS_NOT_IMPLEMENTED if the function is not implemented. SCL1 Version 3.1 - Reference Manual - Page 281 XMS_RequestUMB - XMS_UnlockExtended XMS_UMB_NOT_AVAILABLE if no UMBs are available. Parameters: para - size of requested memory block in paragraphs. One paragraph is 16 Bytes of memory (unsigned int.) UMBpt - pointer to a far pointer to the segment number of the upper memory block if the request is granted. ActualSize - pointer to an unsigned integer value that will hold the actual size of the allocated block in paragraphs or the size of the largest available UMB in paragraphs (unsigned integer). Example: See XMS_Init ----------------------------------------------------------------- XMS_UnlockExtended ----------------------------------------------------------------- Purpose: Unlocks a locked extended memory block. Pointers into the block become invalid and should no longer be used. Prototype: int XMS_UnlockExtended(int handle); Returns: Returns one of the following messages defined in header file SCL1XMS.H: XMS_OK if the block is unlocked. XMS_VDISK_PRESENT if a VDISK device is detected. XMS_NOT_IMPLEMENTED if the function is not implemented. XMS_INVALID_HANDLE if the handle is invalid. XMS_BLOCK_NOT_LOCKED if the block is not locked Parameter: handle - unsigned integer value that holds a handle to the allocated block. Example: See XMS_Init SCL1 Version 3.1 - Reference Manual - Page 282 YesNo ----------------------------------------------------------------- YesNo ----------------------------------------------------------------- Purpose: Displays a YES/NO query box with mouse control buttons. The original screen is restored on exit. Prototype: int YesNo(int NColor,int RColor,int Selection, char *p); Returns: A value of "1" is returned if YES is selected. A value of "2" if NO is selected. You can use the YN_YES and YN_NO constants defined in SCL1.H. Parameters: NColor - color for the YES/NO box (integer). RColor - color 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> int Color1=WHITE_BLACK; int Color2=BLACK_WHITE; #define OK 1 #define CANCEL 2 main() { YN_SetPosition(4,10); /* Set position of the YesNo box to the upper left corner of the screen */ /* use YN_SetUserLang to modify prompts to OK and CANCEL */ YN_SetUserLang("< OK >",2,0x1800,"< CANCEL >",11,0x2e00); do { if(YesNo(Color1,Color2,OK,"Turn YesNo Box\nShadow On?")==OK) YesNoShadowOn(); if(YesNo(Color1,Color2,OK,"Turn YesNo Box\nShadow Off?")==OK) YesNoShadowOff(); }while(YesNo(Color1,Color2,CANCEL,"Exit to DOS?")!= OK); } SCL1 Version 3.1 - Reference Manual - Page 283 YesNoShadowOff - YesNoShadowOn - YNSetPosition ----------------------------------------------------------------- YesNoShadowOff, YesNoShadowOn ----------------------------------------------------------------- Purpose: Displays or disable a shadow effect when using the YesNo function. After any of these functions is called all subsequent calls to the YesNo function will be displayed with (or without) a shadow effect. Prototype: void YesNoShadowOff(void); void YesNoShadowOn(void); Returns: Nothing. Parameters: None. Example: See YesNo See YNSetPosition and YN_SetUserLang. ----------------------------------------------------------------- YNSetPosition ----------------------------------------------------------------- Purpose: Permits changing the position of a YesNo display to any place in the screen. Prototype: void YN_SetPosition(int UpperRow,int LeftCol); Returns: Nothing Parameters: UpperRow - upper row position of the YesNo box (integer). LeftCol - left column position of the YesNo box (integer). Example: See YesNo See YesNoShadowOff, YesNoShadowOn and YN_SetUserLang. SCL1 Version 3.1 - Reference Manual - Page 284 YN_SetUserLang ----------------------------------------------------------------- YN_SetUserLang ----------------------------------------------------------------- Purpose: Modify the default YesNo prompts with your own prompts. Prototype: void YN_SetUserLang(char *prompt1,int offset1, unsigned int key1,char *prompt2,int offset2, unsigned int key2); Returns: Nothing Parameters: prompt1 - char pointer to the first prompt, the "Yes" option. offset1 - position from the border of the box where to display the first prompt (integer). key1 - scan code of the key to be used for selecting prompt1 (unsigned int). prompt2 - char pointer to the second prompt, the "No" option. offset2 - position from the border of the box where to display the second prompt (integer). key2 - scan code of the key to be used for selecting prompt2 (unsigned int). Example: See YesNo See YesNoShadowOff, YesNoShadowOn and YNSetPosition. SCL1 Version 3.1 - Reference Manual - Page 285 YN_SetFrame ----------------------------------------------------------------- YN_SetFrame ----------------------------------------------------------------- Purpose: Modify the default YesNo frame type. Prototype: void YN_SetFrame(int FrameType); Returns: Nothing Parameters: FrameType - any of the frame types defined in Box or GSSBox (integer). See YesNo, YesNoShadowOff, YesNoShadowOn and YNSetPosition. SCL1 Version 3.1 - Reference Manual - Page 286 ZWindow ----------------------------------------------------------------- ZWindow ----------------------------------------------------------------- Purpose: Restores a screen area with a zooming effect. Prototype: void ZWindow(int Color,int UpperRow,int LeftCol, int LowerRow,int RightCol,int Frame,char* Buffer); Returns: Nothing Parameters: Color - color for the area to be restored (integer). UpperRow - upper left row position of the area (integer). LeftCol - upper left column position of the area (integer). LowerRow - lower right row position of the area (integer). RightCol - lower right column position of the area (integer). Frame - frame type to be used (integer). Buffer - pointer to a buffer that holds the screen information. The buffer size is the number of characters * 2. This size can be calculated by using the W_BUF_SIZE macro defined in SCL1.H. Example: See Window SCL1 Version 3.1 - Reference Manual - Page 287 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 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 (a disk drive door left opened, for example). This type of error generates the DOS message "Retry, Abort, Ignore?". Non-critical errors (file not found, for example) are reported by the system but do not generate an interrupt 0x24. SCL1 functions handles non-critical errors in a simple way. Most file functions return zero if the operation was successful, otherwise they return the DOS error code. Your program can then process the error code or you can call the ErrorBox function that will display it. You can change the ErrorBox default error messages (see ErrorBox). SCL1 has the TratInt24 function to deal with DOS critical errors. 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. If DOS generates an interrupt 0x24, instead of its standard message, a window will be opened in the screen and a message indicating the type of error, 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. 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. SCL1 Version 3.1 - Reference Manual - Page 288 Appendix "A" - File Related Functions 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: You must first open or create a file. Use OpenFile to open an existing file (error is reported if the file is not found) or CreateFile to create 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. Once you have a handle to a file you can write or read data. To do it use ReadFile or WriteFile. These 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. 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 using MoveFilePt and MoveFilePt2Offset. Once you have finished working with your file, you must close the file 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 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. SCL1 Version 3.1 - Reference Manual - Page 289 Appendix "B" - Mouse Related Functions 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 the mouse routines. They can be initialized 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. Before returning to DOS the program must un-install the ISR using ResetMouse(). Failure to do so might cause unpredictable problems. These steps can be simplified by using the InitMouse function that performs all the above operations 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 to read the mouse position and the mouse buttons state. 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(); } SCL1 Version 3.1 - Reference Manual - Page 290 Appendix "C" - Screen Related Functions 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 process, SCL1's Video function will determine the type of monitor, the video buffer address and if it is necessary to wait for retrace to reduce snow. To find 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 current video adapter. 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 whether 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). SCL1 Version 3.1 - Reference Manual - Page 291 Appendix "C" - Screen Related Functions SCL1 video functions work only in alphanumeric video modes. You can initialize your system to one of these 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. SCL1 Version 3.1 - Reference Manual - Page 292 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), and the extra keys that enhanced keyboards have (F11 - F12, etc) are defined. SCL1CLOR.H - Color definitions. Example: WHITE_BLUE stands for white characters on blue background. Colors can be highlighted and the blink attribute is also defined. Example: WHITE_RED | HIGHLIGHT WHITE_RED | BLINK SCL1HUGE.H - Definition of huge functions. 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) SCL1EMS - This header file includes the function prototypes for the Expanded Memory Functions. SCL1XMS - This header file includes the function prototypes for the Extended Memory Functions. SCL1 Version 3.1 - Reference Manual - Page 293 Appendix "E" - Dialog Type Functions SCL1 includes several functions 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 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 a 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. You might need a window were the user can browse through a list of items, and 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 type of flexibility, the dialog type functions make use of message interchanges. You can call the function as many times as required, each time requesting an 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 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 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 the function is called. They contain many parameters and it might look as if they involve much effort to define. With the aid of SSG (SCL1 Screen Generator) you can define them very easily. Refer to the included SSG reference manual. SCL1 Version 3.1 - Reference Manual - Page 294 Appendix "E" - Dialog Type Functions 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 similar 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, that you can later modify. 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; /* This initializes the structures to the 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; SCL1 Version 3.1 - Reference Manual - Page 295 Appendix "E" - Dialog Type Functions 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. 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); } SCL1 Version 3.1 - Reference Manual - Page 296 Appendix "E" - Dialog Type Functions THE "DRAW" MESSAGE: Once your structure is defined and initialized you can send messages 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. When you send this message the function will retain the program control until some event occurs. For example, in the case of ScrollWindow, if the user presses the DOWN or UP arrow keys to change a highlighted item, ScrollWindow will return a NEW_POSITION message. If the user presses 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 "EXIT_KEY" 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. SCL1 Version 3.1 - Reference Manual - Page 297 Appendix "E" - Dialog Type Functions 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. 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. SCL1 Version 3.1 - Reference Manual - Page 298 Appendix "E" - Dialog Type Functions 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. 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. } SCL1 Version 3.1 - Reference Manual - Page 299 Appendix "E" - Dialog Type Functions /* 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); 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). SCL1 Version 3.1 - Reference Manual - Page 300 Appendix "E" - Dialog Type Functions 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. SCL1 Version 3.1 - Reference Manual - Page 301 Appendix "E" - Dialog Type Functions 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 they 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: #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; SCL1 Version 3.1 - Reference Manual - Page 302 Appendix "E" - Dialog Type Functions 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. SCL1 Version 3.1 - Reference Manual - Page 303 Appendix "F" - Extended Memory Functions SCL1's extended memory handling functions adhere to the Extended Memory Specifications (XMS), version 2.0, jointly developed by Microsoft Corporation, Lotus Development Corporation, Intel Corporation, and AST Research, Inc. These specifications are the copyright and property of Microsoft Corporation, Lotus Development Corporation, Intel Corporation, and AST Research, Inc. In this Appendix, some information has been literally copied or adapted from these specifications. It is beyond the scope of this appendix to explain in detail the Extended Memory Specifications or how to use them in your programs. It is recommended that you obtain the XMS specification document from any of its developers in order to take full advantage of these functions. Extended Memory allows programs to utilize additional memory found in Intel's 80286 and 80386 based machines. The XMS specifications allow a consistent and machine independent manner to handle this memory. With some restrictions, XMS adds almost 64K to the 640K which programs can access directly. Depending on available hardware, XMS may provide even more memory to DOS programs. XMS also provides programs with a standard method of storing data in extended memory. In order to use the Extended Memory function and XMS driver must be installed in your system by including a DEVICE= statement in the machine's CONFIG.SYS file. It must be installed prior to any other devices or TSRs which use it. DEFINITIONS: Extended Memory - Memory in 80286 and 80386 based machines which is located above the 1MB address boundary. High Memory Area (HMA) - The first 64K of extended memory. The High Memory Area is unique because code can be executed in it while in real mode. The HMA officially starts at FFFF:10h and ends at FFFF:FFFFh making it 64K-16 bytes in length. Upper Memory Blocks (UMBs) - Blocks of memory available on some 80x86 based machines which are located between DOS's 640K limit and the 1MB address boundary. The number, size, and location of these blocks vary widely depending upon the types of hardware adapter cards installed in the machine. Extended Memory Blocks (EMBs) - Blocks of extended memory located above the HMA which can only be used for data storage. A20 Line - The 21st address line of 80x86 CPUs. Enabling the A20 line allows access to the HMA. SCL1 Version 3.1 - Reference Manual - Page 304 Appendix "F" - Extended Memory Functions XMM - Extended Memory Manager. A DOS device driver which implements XMS. XMMs are machine specific but allow programs to use extended memory in a machine-independent manner. For example; HIMEM.SYS, currently distributed by Microsoft. USING XMS FUNCTIONS: To use SCL1's XMS functions first, the program should determine if an XMS driver is installed. It can then use any of the available XMS functions. The following list show the correspondence of SCL1's XMS functions to the function numbers in the XMS specifications. SCL1 Function XMS Function Number ----------------------- ------------------- XMS_Init XMS_GetVersion 0 XMS_RequestHMA 1 XMS_ReleaseHMA 2 XMS_GlobalEnableA20 3 XMS_GlobalDisableA20 4 XMS_LocalEnableA20 5 XMS_LocalDisableA20 6 XMS_QueryA20 7 XMS_QueryFreeExtended 8 XMS_AllocExtended 9 XMS_FreeExtended 10 XMS_MoveExtended 11 XMS_LockExtended 12 XMS_UnlockExtended 13 XMS_GetEMBHandleInfo 14 XMS_ReallocExtended 15 XMS_RequestUMB 16 XMS_ReleaseUMB 17 SCL1 Version 3.1 - Reference Manual - Page 305 Appendix "G" - Expanded Memory Functions SCL1's Expanded Memory Functions adhere to the LIM version 4.0 specifications. Because they are standardized, you avoid potential compatibility problems with other expanded memory programs that also adhere to the memory manager specification. Most standard functions are included, although not all advanced LIM functions have been implemented. In order to use the EMM functions your system must have expanded memory capabilities and a suitable Expanded Memory Manager should have been installed. In this Appendix, some information has been literally copied or adapted from these specifications. It is beyond the scope of this appendix to explain in detail the Expanded Memory Specifications or how to use them in your programs. It is recommended that you obtain the LIM specification document from any of its developers in order to take full advantage of these functions. USING EXPANDED MEMORY FUNCTIONS The general procedure to use the EMS functions is: Determine if EMM is installed by calling the EMS_Init function. Determine if enough expanded memory pages exist for your application. Allocate expanded memory pages. Get the page frame base address. Map in expanded memory pages. Read/write/execute data in expanded memory, just as if it were conventional memory. Return expanded memory pages to expand memory pool before exiting. The following list show the correspondence of SCL1's EMS functions to the function numbers in the EMS specifications. SCL1 Function EMM Function Number ----------------------- ------------------- EMS_Status 1 EMS_PageAdress 2 EMS_AvailableLogPages 3 EMS_Alloc 4 EMS_Map 5 EMS_Free 6 EMS_Version 7 EMS_SavePageMap 8 EMS_RestorePageMap 9 EMS_GetHandleCount 12 EMS_GetHandlePages 13 EMS_GetAllHandlePages 14 EMS_MapMultipleEMS 17 EMS_Realloc 18 EMS_GetHandleName 20 EMS_SetHandleName 20 EMS_Move 24 EMS_Exchange 24 SCL1 Version 3.1 - Reference Manual - Page 306 Appendix "H" - Keyboard Macros A macro is series of keystrokes stored in memory or in a disk file that, when recalled, will perform as if they were keyed in into the keyboard. The number of macros that can be defined at once is limited only by the available memory. Macros can be of up to 32,000 keystrokes in size. The macro capability is available on any function that uses SCL1's keyboard handling functions, they will not be available if you call any of the standard library keyboard functions. If you do not use these macro capabilities, the keyboard related functions will work exactly as in previous versions of SCL1. When you invoke any of the macro related function, the keyboard functions will check to see if any defined macro or trap keyboard combination has been entered and when detected act on them. Macros are stored in a structure type MACROData defined in SCL1.H as follows: typedef struct{ unsigned int key; unsigned int size; unsigned int *buffer; }MACROData; where, key is the key to trigger or invoke the macro. size is the maximum number of keys to accept for the macro. buffer is a pointer to the buffer that will hold the macro. Every macro defined will occupy one array member of this type. All macro related functions will read and/or write to this structure. The simplest way to use the macros is by using the MCR_Init function. This function will do almost everything for you. Every time the key defined for starting and stopping the macro recording process is pressed this function will send messages to your own user defined macro handling function. With these messages you can control the flow of the macro recording and storing. Once a macro is recorded it will immediately become available. You can save to disk the recorded macros using MCR_SaveMacro and you can retrieve macros using MCR_ReadFile, see MCR_Init for an example.Other functions permit more control of the macro creation and use process. SCL1 Version 3.1 - Reference Manual - Page 307 Appendix "I" - Common Compiler Errors When compiling programs you may encounter several Compiler or Linker errors. In this appendix the most common errors and some possible solutions are listed. Unresolved externals - You can get this message from the linker if one or more variables or functions specified in your source code is not found. If it refers to an SCL1 function it means that you have not specified the SCL1 library module needed to properly link your program. See USING SCL1 for more information. Fix-up overflow - You can get this message if you compile your program using a memory model and then thy to link it with an SCL1 library module of a different memory model. Memory models of must be the same. Code exceeds 64K - If you get this message while using the small or compact memory model it means that you must switch to the medium or large memory model. Stack & Data exceeds 64K - If you get this message while using the small or medium memory model it means you that you must switch to the compact or large memory model. You can also get this message while using the compact or large memory model if your initialized static data cannot fit into the default data segment. Try removing some of this data by allocating and initializing buffers using malloc. If this is not possible you have several options depending on your compiler. With Borland compilers switch to the huge memory model. With the Microsoft compilers you can try declaring some of this data (big items) with the far keyword, this will force the compiler to move the data to a far data segment. You can also compile your source with the Gt switch. This switch tells the compiler to put large data items into far memory. Too many segments - The Microsoft linker has a default limit in the number of segments. You can increase this limit by adding the switch SE followed by the number of desired segments (for example, SE:256). undefined struct or constant - If it is an SCL1 related identifier you have to add the include directive with the proper SCL1's header file. See Appendix "D" SCL1 Version 3.1 - Reference Manual - Page 308 Appendix "J" - Character Definition Tables In text modes, characters are defined in character definition tables. The following is a VGA character matrix defining character ASCII 1: matrix byte representation 0 0 0 0 0 0 0 0 0x00 0 0 0 0 0 0 0 0 0x00 0 1 1 1 1 1 1 0 0x7e 1 0 0 0 0 0 0 1 0x81 1 0 1 0 0 1 0 1 0xa5 1 0 0 0 0 0 0 1 0x81 1 0 0 0 0 0 0 1 0x81 1 0 1 1 1 1 0 1 0xbd 1 0 0 1 1 0 0 1 0x99 1 0 0 0 0 0 0 1 0x81 1 0 0 0 0 0 0 1 0x81 0 1 1 1 1 1 1 0 0x7e 0 0 0 0 0 0 0 0 0x00 0 0 0 0 0 0 0 0 0x00 0 0 0 0 0 0 0 0 0x00 0 0 0 0 0 0 0 0 0x00 Each number represents one bit. Since each line has 8 bits it can be represented by one byte. A character definition matrix like this is normally represented by an array of 16 bytes starting with the top line (as seen at the right column). When displayed in the screen, bits set to "1" are displayed in the foreground color and bits set to "0" in the background color. EGA and VGA displays have several character tables used for several text modes: Video Mode 25x40 25x80 28x80 43x80 50x80 VGA 8x16 8x16 8x14 N/A 8x8 EGA 8x14 8x14 N/A 8x8 N/A In EGA and VGA monitors we can modify these tables to create new fonts and even display a graphic in a text screen mode (see BMPCNV.C included in the sample files). SCL1's ModifyCharSet function can be used to modify the character table that the BIOS is currently using. You have to be careful to pass the correct character matrix, so you need to check the type of monitor and the active video mode in order to know which character matrix to use. The easiest way to work with character definitions is to use SSG. Start SSG and modify any character using the SSG character editor (Video Menu, Modify Character Set) and then generate the source (Character Set object). When you save the file SSG will create a function that checks the monitor type and video mode to select the correct character matrix. SCL1 Version 3.1 - Reference Manual - Page 309 Appendix "J" - Character Definition Tables Once a character has been modified it will be active until you change the video mode. SCL1's InitVideo function can be used to reset all characters to their default. You can also restore character definitions from a previously copied table in one of two ways.: 1) Using GetCharTable - This function copies one or more characters from the active table to a buffer. Beware that this characters are always in a 32 scanlines format used by the BIOS when a character table is active. So when you call ModifyCharSet to restore them you must specify that they have 32 scanlines. 2) Using GetCharTableAddress - This function returns a far pointer to one of the BIOS character definition tables stored in ROM. You must specify which character table you desire using constant defined in SCL1.H (GCA_8X8A, GCA_8X8B, GCA_8X14, GCA_8X16). These character definitions cannot be modified so they always have an original copy. Characters are organized in these table in 8, 14 or 16 scanlines (the same they are supposed to have). To create new character definition you can use the SSG character editor or draw a bitmap using Windows' PaintBrush program and using the BMPCNV conversion utility (included as C source file in the samples files) to create character definition out of the bitmap. In this case you must create a bitmap of a size in pixels that is a multiple of eight horizontally and 16, 14 or 8 vertically (depending of the target character matrix). Characters are displayed on the screen in 9 bits horizontal matrix. The extra bit is normally set to the background color to make sure that there is a separation between characters. In the case of ASCII codes 0xC0 to 0xDF (used for graphic characters) the righmost pixel is duplicated to make sure that characters are connected. If you want to duplicate a bitmap image you must use characters 0xC0-0xDF. As you see we're limited to the size of this bitmap. (You can also use BMPCNV to view bitmaps in text mode). Modifying Palette Colors In text modes we have access to 16 different colors plus the border color. The value of these colors is set by the BIOS to defaults each time a video mode is set. Each color of this palette can have a value of 0-63, so although we can only have 16 colors at one time on the screen, we can select these 16 colors from a selection of 64 colors using SCL1's ModifyPalette (modify all palette colors and border color) or ModifyPaletteColor (modify one palette entry). Use SSG Palette editor (Video Menu, Modify Palette) or take a look at the SCL1DEMO Character and Palette under the Video Menu to see the different colors available. SCL1 Version 3.1 - Reference Manual - Page 310 REGISTRATION INFORMATION SCL1 C function Library Version 3.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 $35.00 (or $70.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. You can leave us a message through the Compuserve I.D. No. 70262,1562 or BIX Name jalvira. The latest version of SCL1, sample programs and comments about these programs are available in: TECH BBS (Sysop: José Romero) (809)731-2322 You do not have to be a registered member of this BBS to be able to download SCL1 files. If you call for the first time, after you answer the questionnaire you can locate SCL1 files in the FREE directory under the FILES menu. Though new users have a 15 minutes per call time restrictions, the files located in this directory can be downloaded even if they take longer than 15 minutes to transfer. In order to download more than one file use a batch type protocol. You can leave any comments, suggestions or questions in this BBS directed to JOSE ALVIRA or JOSE LEBRON. We will reply these messages in the same BBS. A german version of SCL1 is available from: Michael Witte Buchholzer Str. 8, D-W-2116 Hanstedt Germany SCL1 Version 3.1 - Reference Manual - Page 311 Index AddExtension . . . . . . . 5 EMS_Move . . . . . . . . . 43 BackgroundOff . . . . . . . 6 EMS_PageAdress . . . . . . 59 BackgroundOn . . . . . . . 9 EMS_Realloc . . . . . . . . 60 Beep . . . . . . . . . . . 9 EMS_RestorePageMap . . . . 61 BigCursor . . . . . . . . . 9 EMS_SavePageMap . . . . . . 62 Bin2Ascii . . . . . . . . . 10 EMS_SetHandleName . . . . . 63 Box . . . . . . . . . . . . 11 EMS_Status . . . . . . . . 64 Buf2Disk . . . . . . . . . 13 EMS_TotalLogPages . . . . . 65 C_SetUserLang . . . . . . . 30 EMS_Version . . . . . . . . 66 Calendar . . . . . . . . . 14 ErrorBox . . . . . . . . . 67 Center . . . . . . . . . . 17 ErrorShadowOff . . . . . . 68 ChangeDumpColor . . . . . . 17 ErrorShadowOn . . . . . . . 68 ChangeExtension . . . . . . 5 FB_SetUserLang . . . . . . 69 CheckChar . . . . . . . . . 18 FB3_SetUserLang . . . . . . 69 CheckEnhancedKeyb . . . . . 19 FieldCheck . . . . . . . . 70 CheckItemList . . . . . . . 21 Fields . . . . . . . . . . 71 CheckMouse . . . . . . . . 22 Fields2 . . . . . . . . . . 74 CheckMouseButton . . . . . 23 File2Buf . . . . . . . . . 96 ClearKeyBuf . . . . . . . . 24 FileBox . . . . . . . . . . 90 ClearWindow . . . . . . . . 25 FileBox2 . . . . . . . . . 91 ClockTick . . . . . . . . . 25 FileBox3 . . . . . . . . . 91 CloseFile . . . . . . . . . 26 FillBlock . . . . . . . . . 97 Cls . . . . . . . . . . . . 27 FindFirst . . . . . . . . . 98 CreateFile . . . . . . . . 28 FindNext . . . . . . . . . 98 CreateWindow . . . . . . . 29 GetCharSet . . . . . . . 101 CursorOff . . . . . . . . . 29 GetCharSetAddress . . . . 101 CursorOn . . . . . . . . . 29 GetCurCol . . . . . . . . 102 Date2Num . . . . . . . . . 31 GetCurLine . . . . . . . 102 DaysPerMonth . . . . . . . 32 GetCurrentDir . . . . . . 102 DeleteFile . . . . . . . . 32 GetCurSize . . . . . . . 103 DestroyWindow . . . . . . . 29 GetDate . . . . . . . . . 104 DialogBox . . . . . . . . . 33 GetDefaultDrive . . . . . 105 DisableMouse . . . . . . . 34 GetDiskFreeSpace . . . . 105 Dissolve . . . . . . . . . 34 GetExtendedAscii . . . . 106 DrawBoxLine . . . . . . . . 36 GetFileMode . . . . . . . 108 DrawItemList . . . . . . . 37 GetFilePt . . . . . . . . 109 DrawLine . . . . . . . . . 38 GetFiles . . . . . . . . 107 DrawMouseButton . . . . . . 39 GetFileSize . . . . . . . 111 EB_SetUserLang . . . . . . 40 GetFreeMem . . . . . . . 111 EMS_Alloc . . . . . . . . . 41 GetKey . . . . . . . . . 112 EMS_AvailableLogPages . . . 42 GetString . . . . . . . . 114 EMS_Exchange . . . . . . . 43 GetTime . . . . . . . . . 115 EMS_Free . . . . . . . . . 46 GSSBox . . . . . . . . . . 11 EMS_GetAllHandlePages . . . 47 HBuf2Disk . . . . . . . . . 13 EMS_GetHandleCount . . . . 48 HFile2Buf . . . . . . . . . 96 EMS_GetHandleName . . . . . 49 HideMouse . . . . . . . . 116 EMS_GetHandlePages . . . . 50 Huge2Far . . . . . . . . 115 EMS_Init . . . . . . . . . 51 I24_SetUserLang . . . . . 123 EMS_Map . . . . . . . . . . 57 InitDrive . . . . . . . . 117 EMS_MapMultipleEMS . . . . 58 InitMouse . . . . . . . . 117 SCL1 Version 3.1 - Reference Manual - Page 312 Index InitUserError . . . . . . 118 PopMenu . . . . . . . . . 196 InitVideo . . . . . . . . 118 PushCursor . . . . . . . 194 InitWData . . . . . . . . 119 ReadFile . . . . . . . . 197 Int24ShadowOff . . . . . 122 ReadPalette . . . . . . . 198 Int24ShadowOn . . . . . . 122 RecordFile . . . . . . . 198 KeyReady . . . . . . . . 124 RemoveDir . . . . . . . . 202 KeyStatus . . . . . . . . 125 RemoveExtension . . . . . 202 LeapYear . . . . . . . . 127 RenameFile . . . . . . . 203 LineEditor . . . . . . . 128 ResetMouse . . . . . . . 204 LinkedList . . . . . . . 136 ResetMouseCur . . . . . . 204 ListManager . . . . . . . 140 RestoreInt10 . . . . . . 248 ListWindow . . . . . . . 142 ScreenDump . . . . . . . 205 LW_MoveTo . . . . . . . . 147 ScrollDown . . . . . . . 206 MakeDir . . . . . . . . . 160 ScrollList . . . . . . . 207 MCR_CloseFile . . . . . . 148 ScrollUp . . . . . . . . 206 MCR_Init . . . . . . . . 148 ScrollWindow . . . . . . 208 MCR_MacroDisable . . . . 153 Select . . . . . . . . . 214 MCR_MacroEnable . . . . . 153 SetBin2AsciiDel . . . . . 217 MCR_MacroExist . . . . . 153 SetCurPos . . . . . . . . 218 MCR_Play . . . . . . . . 154 SetCurSize . . . . . . . 218 MCR_ReadFile . . . . . . 154 SetDialogColor . . . . . 219 MCR_Record . . . . . . . 155 SetErrorBoxColor . . . . 219 MCR_RegisterBackF . . . . 155 SetFileMode . . . . . . . 220 MCR_RegisterMacro . . . . 156 SetHorLimit . . . . . . . 221 MCR_RegisterTrapKey . . . 157 SetInt24Colors . . . . . 222 MCR_Report . . . . . . . 157 SetMouseCur . . . . . . . 222 MCR_SaveMacro . . . . . . 158 SetMouseIsr . . . . . . . 222 MCR_UnregisterBackF . . . 159 SetMousePos . . . . . . . 224 MCR_UnregisterMacro . . . 159 SetShadowColor . . . . . 225 MCR_UnregisterTrapKey . . 159 SetUserBox . . . . . . . 225 Menu . . . . . . . . . . 161 SetUserBoxLine . . . . . 226 MenuSystem . . . . . . . 164 SetVerLimit . . . . . . . 221 MenuSystem2 . . . . . . . 164 SetVideo25 . . . . . . . 229 MESS_SetPosition . . . . 178 SetVideo28 . . . . . . . 229 MessageOff . . . . . . . 179 SetVideo4350 . . . . . . 229 MessageOn . . . . . . . . 180 SetVideoMode . . . . . . 227 MessageShadowOff . . . . 180 SetVideoPage . . . . . . 228 MessageShadowOn . . . . . 180 Shadow . . . . . . . . . 230 ModifyCharSet . . . . . . 182 ShellSort . . . . . . . . 231 ModifyPalette . . . . . . 184 ShowMouse . . . . . . . . 116 ModifyPaletteColor . . . 185 SortPointers . . . . . . 233 MouseButton . . . . . . . 187 Sound . . . . . . . . . . 234 MouseMenu . . . . . . . . 161 SoundOff . . . . . . . . 234 MouseMenu2 . . . . . . . 161 SoundOn . . . . . . . . . 234 MoveFilePt . . . . . . . 189 StopWatch . . . . . . . . 235 MoveFilePt2Offset . . . . 190 SW_MoveTo . . . . . . . . 147 Num2Date . . . . . . . . 190 TagItem . . . . . . . . . 236 OpenFile . . . . . . . . 191 TagList . . . . . . . . . 238 PercentBar . . . . . . . 193 TagList2 . . . . . . . . 240 PopCursor . . . . . . . . 194 TagMenu . . . . . . . . . 242 SCL1 Version 3.1 - Reference Manual - Page 313 Index TextWindow . . . . . . . 245 ZWindow287 TL_SetUserLang . . . . . 248 TrapBIOSScreenWrite . . . 248 TrapInt10 . . . . . . . . 248 TrapInt23 . . . . . . . . 249 TrapInt24 . . . . . . . . 250 TSound . . . . . . . . . 251 Video . . . . . . . . . . 251 VideoConfig . . . . . . . 252 WaitKeyMouse . . . . . . 254 WaitTime . . . . . . . . 254 WF_SetUserLang . . . . . . 69 WFileBox . . . . . . . . . 91 Window . . . . . . . . . 254 WriteChar . . . . . . . . 256 WriteFile . . . . . . . . 257 WriteOffLen . . . . . . . 257 WriteOffset . . . . . . . 258 WriteScreen . . . . . . . 259 WriteScreenC . . . . . . 259 WriteScreenCLen . . . . . 260 WriteScreenLen . . . . . 260 WriteScreenR . . . . . . 259 WriteScreenRLen . . . . . 260 WriteWindow . . . . . . . 262 XMS_AllocExtended . . . . 263 XMS_FreeExtended . . . . 264 XMS_GetEMBHandleInfo . . 265 XMS_GetVersion . . . . . 266 XMS_GlobalDisableA20 . . 267 XMS_GlobalEnableA20 . . . 267 XMS_Init . . . . . . . . 268 XMS_LocalDisableA20 . . . 275 XMS_LocalEnableA20 . . . 275 XMS_LockExtended . . . . 276 XMS_MoveExtended . . . . 277 XMS_QueryA20 . . . . . . 278 XMS_QueryFreeExtended . . 279 XMS_ReallocExtended . . . 279 XMS_ReleaseHMA . . . . . 280 XMS_ReleaseUMB . . . . . 281 XMS_RequestHMA . . . . . 280 XMS_RequestUMB . . . . . 281 XMS_UnlockExtended . . . 282 YesNo . . . . . . . . . . 283 YesNoShadowOff . . . . . 284 YesNoShadowOn . . . . . . 284 YN_SetFrame . . . . . . . 286 YN_SetUserLang . . . . . 285 YNSetPosition . . . . . . 284 SCL1 Version 3.1 - Reference Manual - Page 314