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