Category : C Source Code
Archive   : CMAGIC15.ZIP
Filename : MAGIC.3

Continued from MAGIC.2

*************************************************************
void resetmouse(void) - function

Usage: resetmouse()

Description:
This restores the mouse situation to it's default
parameters. The mouse pointer will be relocated to the center
of the screen and the left, center (if equipped) and right
mouse button status will be 0. The mouse will be initialized
to the current graphics or text mode.

Considerations:
Resetmouse() is automatically implemented anytime
cgahivideo(), vgalovideo(), bestvideo(), etc are called.

See also:
poll(), pointertoxy(), pointeron(), pointeroff(),
setmousecolumns(), setmouserows()

*************************************************************
void restore(void) - function

Usage: restore()

Description:
Restore() replaces the screen contents with a picture
saved before the last call to pop().
Getanykey(), getyn(), dialog(), or menu(), call restore()
automatically when they finish, but pop() does not. Restore()
also frees the memory which was held for the saved screen
image.

Considerations:
In graphics mode, it is easily possible to exceed avail-
able RAM space. Call restore() as soon as possible when done
with a pop-up. In text mode, repeated calls to restore()
brings back the image preceding each pop() up to 10 layers
deep. Restore() is a smart procedure, if called more times
than the number of stored screens, it has no effect.

See Also
pop(), clearsents()

Example:

#include
#include
void main() {
magic_setup();
pile("This box is going to");
pile("be difficult to read");
pop(1,1);
clearsents();
delay(1000);
pile("because this screen");
pile("is going to cover it up");
pile("Press any key to get rid");
pile("of this box");
pop(5,2);
waitforuser();
restore();
waitforuser();
restore();
delay(1000);
cleanup();
}

Performance of example:
A box containing two lines of text appears in the extreme
upper left corner, then one second later, a four-line box
partially covers it up. When the user presses a key, the
second box disappears so that the first one can be seen
clearly. When the user presses a key again, the first box
disappears leaving a blank screen. After a one second delay,
the program terminates cleanly.

*************************************************************
void restoresettings(void) - function

Usage: restoresettings()

Description:
This function is used after a previous call to
savesettings(). Savesettings() memorizes linestyle, viewport,
color and font information when it is called. Then you can
temporary change these settings by using pop(), or functions
of your own. When done, call restoresettings() and
linestyle, viewport, text and justification settings will be
reset to their previous condition.

Considerations:
Restoresettings() has no effect in text mode.
Getanykey(), getyn(), dialog() and menu() call savesettings()
and restoresettings() automatically.

See Also: savesettings(), pop()

Example:
#include
#include
void main(){
magic_setup();
bestvideo();
triplex();
setcolor(YELLOW);
setlinestyle(1,0,3);
settextjustify(LEFT_TEXT,CENTER_TEXT);
.
.
savesettings();
setcolor(GREEN);
gothic();
setlinestyle(0,0,1);
settextjustify(CENTER_TEXT,BOTTOM_TEXT);
.
.
restoresettings();
outtextxy(10,10,"Everything is as it was.");
waitforuser();
cleanup();
}

Performance of example: Triplex font is selected, current
drawing color is set to yellow, line style is set to thick
dotted line, and justification is set to left and center.
Some other, unidentified programming happens, then
savesettings() is called. Current color is set to GREEN,
font to Gothic, linestyle becomes thin, dotted, and
justification is set to center,bottom. Some more
unidentified programming happens.
Then restoresettings() is called, and everything reverts
to the settings at the time savesettings() was called.
Therefore, the string, "Everything is at it was." will be
shown in the previous color of YELLOW, in Triplex font, with
left and center justification.

*************************************************************
char right - Global Variable

Usage: /* example */ if (right) break;

Description:
Right is a global char variable used to record the status
of the right mouse button. If right = 1 then the right mouse
button has been pressed, otherwise right = 0.

Considerations:
The status of right will change with every call to poll(),
waste(), resetmouse() or procedures within Magic which handle
text or pop up boxes.

See Also: poll(), waste(), ResetMouse(), center, left

Example:
#include
void main() {
magic_setup();
waste();
pile("Nothing will change until you click the");
pile("right mouse button");
pop(-1,-1);
do poll; while (!right);
}

Performance of example:
A box containing two lines of text will stay on the screen
until the user clicks the right mouse button. The program
will then terminate.

*************************************************************
void sansserif(void) - function

Usage: sansserif()

Description:
This function causes outtext() and outtextxy() to generate
text in the "sansserif" stroked font.

Considerations:
SANS.CHR is linked into .EXE file and RAM usage and disk
space requirements increase.

See Also:
triplex(), little(), gothic(), bold(), script(),
italic(), complex(), simple(), bitmap(), european()

Example:
#include
#include
void main(){
magic_setup();
bestvideo();
sansserif();
outtextxy(0,0,"SansSerif font");
waitforuser();
cleanup();
}

Performance of example:
Program writes "SansSerif font" on screen using the
"sansserif" font.

*************************************************************
void savescreen(void) - function

Usage: savescreen()

Description:
Savescreen() saves the current screen image to RAM so
that it can be restored at a later time.
In text mode, the cursor location is also saved.

Considerations:
In graphics modes, savescreen() will hold only one
memorized screen at a time. In text mode, it will memorize up
to 10 screens simultaneously. Savescreen() is called
automatically by pop() and the functions which use pop().
In text modes, the last screen saved is the first
restored. They are restored in a last saved, first restored
order.

See Also:
restore(), pop(), getanykey(), getyn(), dialog(), menu()

Example:
#include
#include
void main() {
magic_setup();
savescreen();
xclear();
printf("Whatever was here before, will be restored.");
waitforuser();
restore();
}

Performance of example:
As the program starts, the image of the current screen is
saved to RAM, the screen is cleared and a sentence appears.
When the user presses any key, the previous screen image
reappears and the previous cursor position is restored.

*************************************************************
void savescreeng(void) - function

Usage: This function is used internally by the Magic library.
Direct use of this function is not recommended.

Description:
When in a graphics mode, savescreen() passes control to
this function.

*************************************************************
void savesettings(void) - function

Usage: savesettings()

Description:
Before a call to pop() or any programming which may
affect current settings of linestyle, font, justification or
color, call this function to memorize the current settings.
When you want to restore the memorized settings, call
restoresettings().

Considerations:
Getanykey(), getyn(), dialog() and menu() call
savesettings() and restoresettings() automatically.

Example:
#include
#include
void main(){
magic_setup();
bestvideo();
triplex();
setcolor(YELLOW);
setlinestyle(1,0,3);
settextjustify(LEFT_TEXT,CENTER_TEXT);
.
.
savesettings();
setcolor(GREEN);
gothic();
setlinestyle(0,0,1);
settextjustify(CENTER_TEXT,BOTTOM_TEXT);
.
.
restoresettings();
outtextxy(10,10,"Everything is as it was.");
waitforuser();
cleanup();
}

Performance of example: Triplex font is selected, current
drawing color is set to yellow, line style is set to thick
dotted line, and justification is set to left and center.
Some other, unidentified programming happens, then
savesettings() is called. Current color is set to GREEN,
font to Gothic, linestyle becomes thin, dotted, and
justification is set to center,bottom. Some more
unidentified programming happens.
Then restoresettings() is called, and everything reverts
to the settings at the time savesettings() was called.
Therefore, the string, "Everything is at it was." will be
shown in the previous color of YELLOW, in Triplex font, with
left and center justification.

*************************************************************
char screencount - Global Variable

Usage: This is used internally by the Magic library. Direct
manipulation is not recommended.

Description:
In text mode, up to 10 calls to pop(), dialog(), getyn(),
getanykey() or menu() can overlap each other. Each structure
of screen information saved under the pop-up boxes is
numbered and tracked with screencount. When screencount is
0, no images are currently saved.

*************************************************************
void script(void) - function

Usage: script()

Description:
This function causes outtext() and outtextxy() to generate
text in the "script" stroked font.

Considerations:
SCRI.CHR is linked into .EXE file and RAM usage and disk
space requirements increase. This font will not work with
older versions of Turbo C.

See Also:
triplex(), little(), gothic(), sansserif(), bold(),
italic(), complex(), simple(), bitmap(), european()

Example:
#include
#include
void main(){
magic_setup();
bestvideo();
script();
outtextxy(0,0,"Script font");
waitforuser();
cleanup();
}

Performance of example:
Program writes "Script font" on screen using the "script"
font.

*************************************************************
char sent[81][46] - Global Variable

Usage: /* example */ strcpy(sent[1],"test");

Description:
Sent[81][46] is a two-dimensional array of characters. If
you are new to C, don't think of it that way, however.
Instead, think of it as a collection of up to 46 strings or
sentences. Each string can be up to 80 characters long, plus
the necessary, C-standard, null-termination, which puts an
ASCII #0 at the end of each string to keep track of how long
it is. (Many C functions look for the #0 at the end of
strings.)
Sent[] is used by pop() and the function which use pop(),
such as getanykey(), getyn(), dialog() and menu(). You can
access it automatically with pile() or directly with the
Borland/Turbo C/C++ string handling functions such as
strcpy(), strcat(), printf(), etc. Most often, you work with
one string from sent[] at a time, and you access the string
you want with a variable, as in the usage example above.
Use the function, figurehowmany() to determine the current
number of strings in use. Use clearsents() to reset all
strings in [sent] to "null" or empty.

Considerations:
Although sent[] allows up to 46 strings of up to 80
characters each, in many uses, you can't use that much.
Pop() and the functions which use pop() require space on the
screen for borders and shadows. In standard text mode (80 x
25) you can actually use only 75 characters per string and
only up to 22 strings.
There is a limit to the maximum size of pop-up boxes using
sent[]. For instance, in VGA-HI graphics mode, the limit is
about 20 lines of text with the longest line being about 40
characters long.

See Also:
pop(), getanykey(), getyn() dialog(), menu(), clearsents(),
answer(), restore(), pile(), figurehowmany(),
figurehowlong(), howmany, howlong

Example:
#include
#include
void main() {
magic_setup();
strcat(sent[1],"This is a way to avoid");
strcat(sent[2],"the pile() function.");
getanykey(-1,-1);
}

Performance of example:
Two strings are assigned to sent[]. They are displayed with
getanykey() until the user presses a key.

*************************************************************
void setmousecolumns(int high, int low) - function

Usage: setmousecolumns(high,low)

Description:
You can limit the travel of the mouse on the screen with
setmousecolumns() and setmouserows(). Setmousecolumns()
needs two integer numbers, the first is the maximum column
that the mouse is allowed and the second is the minimum
column.

Considerations:
Text mode is usually based on CGA high-res (640 x 200). To
work with a specific text location, divide the mouse x and y
coordinates by 8. To place a character in the third column of
the second row of the screen (near the upper left corner) you
would work at coordinate 16,8.
Do not use this procedure unless a mouse is installed.
This will work fine in all text and graphics modes. Full
screen size for mouse movement in standard text mode (80 x
25) characters is the same as CGA-HI or EGA-Lo, 640 x 200
pixels. Each character essentially occupies a space of 8 x 8
pixels, although in text mode, the mouse moves a block (8
pixels) at a time. So, to restrict mouse movement to the
upper left quarter of the screen you would do this:
setmousecolumns(319,0); setmouserows(99,0);.

See Also:
poll(), pointertoxy(), setmouserows(), mouseinstalled()

Example:
#include
void main() {
magic_setup();
vgavideo();
setmousecolumns(319,0);
setmouserows(199,0);
pointeron();
do poll; while (!left);
}

Performance of example:
This example sets the video mode to VGA but allows the
mouse to move only within the upper left corner of the screen
as if working with the more limited resolution of CGA 4-color
mode.

*************************************************************
void setmouserows(int high, int low) - function

Usage: setmouserows(high,low)

Description:
You can limit the travel of the mouse on the screen with
setmousecolumns() and setmouserows(). Setmouserows() needs
two integer numbers, the first is the maximum row that the
mouse is allowed and the second is the minimum row.

Considerations:
Text mode is usually based on CGA high-res (640 x 200). To
work with a specific text location, divide the mouse x and y
coordinates by 8. To place a character in the third column of
the second row of the screen (near the upper left corner) you
would work at coordinate 16,8.
Do not use this procedure unless a mouse is installed.
This will work fine in all text and graphics modes. See
setmousecolumns() for more details.

See Also:
poll(), pointertoxy(), setmousecolumns(), mouseinstalled()

Example:
#include
void main() {
magic_setup();
vgavideo();
setmousecolumns(319,0);
setmouserows(199,0);
pointeron();
do poll; while (!left);
}

Performance of example:
This example sets the video mode to VGA but allows the
mouse to move only within the upper left corner of the screen
as if working with the more limited resolution of CGA 4-color
mode.

*************************************************************
char shadow - Global Variable

Usage: shadow = color;

Description:
This sets the color of shadows at the bottom and right edge
of pop-up text boxes, where 'color' is an integer from 0 to
15 or a color constant as defined GRAPHICS.H or CONIO.H.
Works in graphics and text mode.

Considerations:
May not have the expected effect when used with the limited
palettes of 4-color CGA (mode 0,1 or 2), 2-color CGA or
Hercules. In text mode, only 8 colors are available: 0 - 7.

See also: maintext, mainback, boxtext, boxback, bartext,
barback, border.

Example:
#include
void main() {
magic_setup();
pile("test");
shadow = GREEN;
getanykey(-1,-1);
}

Performance of example:
A text box pops up with a green shadow.

*************************************************************
void simple(void) - function

Usage: simple()

Description:
This function causes outtext() and outtextxy() to generate
text in the "simple" (a.k.a. "simplex") stroked font.

Considerations:
SIMP.CHR is linked into .EXE file and RAM usage and disk
space requirements increase. This font will not work with
older versions of Turbo C.

See Also:
triplex(), little(), gothic(), sansserif(), script(),
italic(), complex(), simple(), bitmap(), european()

Example:
#include
#include
void main(){
magic_setup();
bestvideo();
simple();
outtextxy(0,0,"Simplex font");
waitforuser();
cleanup();
}

Performance of example:
Program writes "Simplex font" on screen using the "simple"
font.

*************************************************************
void sorry(void) - function

Usage: sorry()

Description:
Sorry() makes a sound typically indicating an incorrect
response to a question.

Considerations:
The global variable musicon must be greater than 0 or
sorry() will not make a sound.

See Also:
musicon, twinkle(), pink(), sounddown(), soundup() {Magic}
sound(), nosound(), delay() {Borland}

Example:
include
void main() {
magic_setup();
musicon = 1;
sorry();
}

Performance of example:
The sorry sound plays.

*************************************************************
void sounddown(void) - function

Usage: sounddown()

Description:
Sounddown() makes a sound typically indicating an event
has completed. It is called automatically by restore() and
the functions that use restore() when musicon > 0.

Considerations:
The global variable musicon must be greater than 0 or
sounddown() will not make a sound.

See Also:
musicon, sorry(), twinkle(), pink(), soundup() {Magic}
sound(), nosound(), delay() {Borland}

Example:
include
void main() {
magic_setup();
musicon = 0; /* temporary lock out sounds so */
/* getanykey()'s sound effect won't */
/* interfere. */

pile("Do you want to hear sounddown?");
getanykey(-1,-1);
if (u == 'Y') musicon = 1;
sounddown();
}

Performance of example:
If the user answers the question affirmatively,
sounddown() will play it's sound effect.

*************************************************************
void soundup(void) - function

Usage: soundup()

Description:
Soundup() makes a sound typically indicating the
beginning of an event. It is called automatically by pop()
and the functions that use pop() when musicon > 0.

Considerations:
The global variable musicon must be greater than 0 or
sounddown() will not make a sound.

See Also:
musicon, sorry(), twinkle(), pink(), sounddown() {Magic}
sound(), nosound(), delay() {Borland}

Example:
include
void main() {
magic_setup();
musicon = 0; /* temporary lock out sounds so */
/* getanykey()'s sound effect won't */
/* interfere. */
pile("Do you want to hear soundup?");
getanykey(-1,-1);
if (u == 'Y') musicon = 1;
soundup();
}

Performance of example:
If the user answers the question affirmatively,
soundup() will play it's sound effect.

*************************************************************
void standardcolors(void) - function

Usage: standardcolors()

Description:
This is used internally by the Magic Library to choose
functional and good looking colors for pop(), getanykey(),
getyn(), dialog() and menu(). These colors will work on a
monochrome display even if the graphics mode is 16 or 256
colors. These will also be correct if in CGA modes or in
Hercules mode.

Considerations:
Standardcolors() is called automatically everytime
graphics (or text) mode is changed by the functions in the
Magic library. You can also restore "default" colors by
calling this function anywhere within your program.

See Also: textvideo(), bestvideo(), cgalovideo(),
cgahivideo(), egalovideo(), egahivideo(), hercvideo(),
vgalovideo(), vgahivideo(), bestvideo(), maintext, mainback,
boxtext, boxback, bartext, barback, border, shadow.

Example:
#include
#include
void main(){
magic_setup();
bestvideo();
mainback = BLUE;
boxtext = WHITE;
.
.
standardcolors();
pile("No matter what we did to the colors");
pile("earlier in this program, they'll be");
pile("ok now!");
getanykey(-1,-1);
}

Performance of example:
Some color variables are changed early in the program.
Some unidentified programming happens. Standardcolors() is
called to restore the default pop-up box colors. Then two
lines are printed via getanykey() which are properly visible.

*************************************************************
void standardvideo(void)

Usage: Standaradvideo() is used internally by the Magic
Library. Direct use of this function is not recommended.

Description:
This function sets up the video environment for graphics
changes. It calls standardcolors(), sets the global char
variable vmode, and resets the mouse if installed.

*************************************************************
void textvideo(void) - function

Usage: textvideo()

Description:
This returns a program from a graphics video mode to text
mode, the default startup condition. The screen is cleared.

Considerations:
Any memory held for a saved screen from a pop-up box will
be released. The global char variable vmode is set to 0.

See Also:
bestvideo(), cgalovideo(), cgahivideo() hercvideo(),
egalovideo() egahivideo(), vgalovideo(), vgahivideo()

Example:
#include
void main() {
magic_setup();
bestvideo();
pile("This is graphics mode");
pile("Press any key to see text mode");
getanykey(-1,-1);
textvideo();
pile("This is text mode");
pile("Press any key to quit");
getanykey(-1,-1);
}

Performance of example:
A box pops up in the best graphics mode the computer can
display. When the user presses a key, the computer switches
to text video mode and another box appears until the user
presses a key again.

*************************************************************
void triplex(void) - function

Usage: triplex()

Description:
This function causes outtext() and outtextxy() to generate
text in the "triplex" stroked font.

Considerations:
TRIP.CHR is linked into .EXE file and RAM usage and disk
space requirements increase.

See Also:
bold(), little(), gothic(), sansserif(), script(),
italic(), complex(), simple(), bitmap(), european()

Example:
#include
#include
void main(){
magic_setup();
bestvideo();
triplex();
outtextxy(0,0,"Triplex font");
waitforuser();
cleanup();
}

Performance of example:
Program writes "Triplex font" on screen using the "triplex"
font.

*************************************************************
void twinkle(void) - function

Usage: twinkle()

Description:
Twinkle() makes a sound typically indicating that an
event has completed positively.

Considerations:
The global variable musicon must be greater than 0 or
sounddown() will not make a sound.

See Also:
musicon, pink(), bugle(), soundup(), sounddown() {Magic}
sound(), nosound(), delay() {Borland}

Example:
include
void main() {
magic_setup();
musicon = 0; /* temporary lock out sounds so */
/* getanykey()'s sound effect won't */
/* interfere. */
pile("Do you want to hear twinkle?");
getanykey(-1,-1);
if (u == 'Y') musicon = 1;
twinkle();
}

Performance of example:
If the user answers the question affirmatively,
twinkle() will play it's sound effect.

*************************************************************
unsigned char u - Global Variable

Usage: /* example */ u = getch();

Description:
"u" is a general purpose global unsigned char variable
declared in MAGIC.H for internal use, but also available for
any use within your program. U originally stood for
UserInput.

Considerations:
U is reset by several of the functions and procedures in
the Magic library. Do not assume the value of u will remain
the same after use of functions such as dialog(),
xreadkey(), etc.

Example:
#include
void main() {
magic_setup();
.
.
pile("Do you want to quit? (Y/N)");
getyn(-1,-1);
if (u == 'Y') exit(0);
.
.
}

Performance of example:
If the user answers affirmatively, u will be set to 'Y'
and the program will end.

*************************************************************
char vga256driver - Global Variable

Usage: For internal use by the Magic library only. Direct
manipulation of this variable is not recommended.

Description: A variable used to identify the 256-color VGA
driver.

*************************************************************
void vgalovideo(void) - function

Usage: vgalovideo()

Description:
This initializes the system in VGA 256-color graphics mode.
VGA256 video driver will be automatically compiled into the
.EXE program file, eliminating the need for external
VGA256.BGI file (not actually supplied by Borland). Graph
mode is set to 0, 320 x 200 resolution, 256 colors.

Considerations:
Will not work on computers unless equipped with VGA.
Graphmode is initially set to 0 (see Borland manual for more
details). Will not work with older Turbo C compilers.

See Also:
bestvideo(), cgalovideo(), cgahivideo, hercvideo(),
egalovideo() egahivideo(), vgahivideo(), textvideo(),
cleanup() {Magic} setgraphmode(), setrgbpalette() {Borland}

Example:
#include
#include
void main() {
magic_setup();
vgalovideo();
setcolor(153);
rectangle(10,10,309,189);
waitforuser();
cleanup();
}

Performance of example:
The system is put in VGA-256 graphics mode. A large
dark purple rectangle is displayed until any key is pressed.

*************************************************************
void vgahivideo(void) - function

Usage: vgavideo()

Description:
This initializes the system in VGA graphics mode. VGA video
driver will be automatically compiled into the .EXE program
file, eliminating the need for external EGAVGA.BGI file.
Graph mode is set to 2, 640 x 480 resolution, 16 colors.

Considerations:
Will not work on computers unless equipped with VGA.
Graphmode is initially set to 2 (see Borland manual for more
details).

See Also:
bestvideo(), cgalovideo(), cgahivideo, hercvideo(),
egalovideo() egahivideo(), vgalovideo(), textvideo(),
cleanup() {Magic} setgraphmode() {Borland}

Example:
#include
#include
void main() {
magic_setup();
vgavideo();
rectangle(10,10,629,469);
waitforuser();
cleanup();
}

Performance of example:
The system is put in VGA graphics mode. A large rectangle is
displayed until any key is pressed.

*************************************************************
char vmode - Global Variable

Usage: /* example */ if (vmode == 0) printf("text mode");

Description:
Vmode is a global char variable used internally by the
Magic library to keep track of the current graphics (or text)
mode. Direct changing of this variable is not recommended,
but you can test it to find out the current graphics mode.

See Also: bestvideo(), cgalovideo(), cgahivideo(),
egalovideo(), egahivideo(), hercvideo(), vgalovideo(),
vgahivideo() textvideo()

Example:

#include
#include
#include
void main(){
magic_setup();
bestvideo();
switch (vmode) {
case 0 : strcpy(sent[1],"text mode"); break;
case 1 : strcpy(sent[1],"CGA-HI"); break;
case 2 : strcpy(sent[1],"CGA-LO"); break;
case 3 : strcpy(sent[1],"EGA-LO"); break;
case 4 : strcpy(sent[1],"EGA-HI"); break;
case 5 : strcpy(sent[1],"Hercules"); break;
case 6 : strcpy(sent[1],"VGA-HI"); break;
case 7 : strcpy(sent[1],"VGA-LO");
}
strcat(sent[1]," is best video mode");
strcpy(sent[2],"for this computer.");
getanykey(-1,-1);
}

Performance of example:
Computer is set to highest-possible resolution graphics
mode with bestvideo(); Then vmode is tested and sent[1] is
assigned a string representing the video mode. A box pops up
indicating the best video mode for your computer.

*************************************************************
void waitforuser(void) - function

Usage: waitforuser()

Description:
This simple procedure stalls the computer until the user
presses a key or clicks a mouse button. This function is the
same as holdon().

See Also:
pop(), xreadkey(), holdon()
Example:

#include
#include
void main() {
magic_setup();
bestvideo();
triplex();
settextstyle(1,3,5);
setcolor(LIGHTRED);
outtextxy(100,90,"Press any key");
waitforuser();
cleanup();
}


Performance of example:
This program displays the words, "Press any key"
(sideways) then waits for the user to press a key or click a
mouse button.

*************************************************************
void waste(void) - function

Usage: waste()

Description:
This procedure makes sure there is nothing in the
keyboard buffer. If a mouse is installed, it also waits until
there are no mouse buttons pressed. u is assigned 126, an
uncommon ASCII character.

Considerations:

See Also:
pop(), xreadkey(), wastemouse()

Example:
#include
#include
#include
void main() {
magic_setup();
printf("Without Waste, keyboard buffer could cause\n");
printf("portions of the program to skid past before\n");
printf("the user knows what is happening\n");
waste();
u = getch();
clrscr();
printf("This is a problem when the user holds a key\n");
printf("down too long");
waste();
u = getch();
clrscr();
}

Performance of example:
Three lines appear on the screen. The keyboard buffer is
cleared out and the program waits until no mouse buttons are
pressed. Then the program waits for a key to be pressed.
Then the screen is cleared and two more lines of text appear.
Again, Waste clears the buffer and waits if a mouse button
is pressed, and then waits for the user to do something. Then
the screen clears and the program terminates.

*************************************************************
void xclear(void) - function

Usage: xclear()

Description:
Clears the screen and sets the background color to
mainback.

Considerations:
You may not get the effect expected when in CGA or
Hercules modes if the selected mainback color is not one
in the current color palette.

See Also:
bestvideo(), hercvideo(), cgavideo(), etc, mainback {Magic};
setgraphmode(), setcolor(), etc. {Borland}

Example:
#include
#include
main(){
magic_setup();
vgavideo();
rectangle(10,10,20,20);
pile("Press any key...");
pop(30,30);
waitforuser();
mainback = MAGENTA;
xclear();
pile("Press any key...");
pop(400,400);
waste();
waitforuser();
}

Performance of example:
A small square appears near the upper left corner of the
screen along with a box with a line of text. When a key is
pressed, the screen clears and a box containing one line of
text appears near the lower right corner and the background
color will be magenta. When a key is pressed again, the
program ends.

*************************************************************
void xclearg(void) - function

Usage: Used internally by the Magic library. Not recommended
for direct usage.

Description:
Xclearg() is called by xclear to clear screen when in a
graphics mode.

*************************************************************
char xcursor[10], ycursor[10] - Global Variables

Usage: Xcursor is used internally by the Magic library.
Direct manipulation is not recommended.

Description:
These are sets of 10 x and y locations to memorize the
position of the cursor in any of 10 layers of text mode
pop-ups. When the screens are restored, the cursor is also
returned to the correct locations.


*************************************************************
void xreadkey(void) - function

Usage: /* example */ u = xreadkey()

Description:
Like getch(), this returns a character to the global
unsigned char "u" as soon as a key is struck. Additionally,
xreadkey, returns a character if a mouse button is clicked.
If the left button is clicked, u will be set to 13, if the
right button is clicked, u will be 27.

Considerations:
Xreadkey() also returns a value in the global char
keydetect. If a mouse button was pressed, keydetect will be
0. If a standard alphanumeric key was pressed, keydetect will
be 1, and if an extended key, keydetect will be set to 2.
If an extended key was pressed, the preceding ASCII #0
will be ignored and the second character in the sequence will
be returned. For example, when the [F1] key is pressed, it
puts #0 and ';' in the keyboard buffer. Xreadkey() will set
u to ';' and keydetect to 2. The #0 will be discarded.

See Also:
xreadln(), waste() keydetect {Magic}; getch(), getche(),
(and related) {Borland}

Example:
#include
#include
void main() {
int i;
magic_setup();
.
.
do {
xreadkey();
u = toupper(u);
if (keydetect == 2) { //then it must be a function key
if (u == 'H') up_arrow_was_pressed();
if (u == 'P') down_arrow_was_pressed();
}
}
while (u != 27);
.
.
}

Performance of example:
Computer waits for user input. If the user presses the up
or down arrow keys, then the fictitious
up_arrow_was_pressed() or down_arrow_was_pressed() functions
execute. This repeats until the user presses the [Esc] key
(#27).

*************************************************************
void xreadln(int x, int y, int h) - Function

Usage: /* example */ Tempstring := xreadln(x,y,h)

Description:
You will find this very useful in database applications
where the user has to fill in blanks in a form. Unlike
Borland's gets() function this allows you to limit the length
of a string the user can type, and it works in text or in
graphics modes.
This is similar to gotoxy() combined with gets(). Of
course, it also works in graphics modes. Xreadln() needs
three integer variables. The first two are the x and y screen
coordinates of the upper left corner of the place where the
user's input will be displayed. X is the horizontal position
and y is the vertical. In text video mode the upper left
corner of the screen is 1,1 and the lower right corner is
80,25. In graphics modes, the upper left corner is 0,0 and
the lower right varies. In the CGA 320x200 mode, for
instance, the lower right corner would be 319,199.
The last number required, h, is an integer for the number
of characters you will allow in the string. Example: if you
have a form in which the user is to type a 4-digit number in
a space, you call xreadln() with the x and y position of the
start of the space, then 4, to limit the length of the number
the user may enter to 4 digits. When the user presses [Esc]
or [Enter] or clicks a mouse button, xreadln is finished.
Xreadln() returns a string in the global unsigned char
variable, "answer".

Considerations:
Xreadln() calls waste() before any other action. Maximum
possible string length is 75 characters. This procedure uses
xreadkey(), so with wise programming you can answer function
key responses and mouse actions within the typing of a
string. This function is useful for reading from the keyboard
only, not for reading files.
Always set textcolor and textbackground before calling
xreadln, because otherwise, it will use the most recently
assigned colors, which might be shadow and border, (default
black and black!) after a pop-up box.
No automatic centering is available. Negative coordinates
will have unpredictable results - probably a crash!

See Also:
xreadkey(), waste() {Magic}; getch(), gets() and related
{Borland}

Example:
#include
#include
#include
void main() {
char namestring[40];
magic_setup();
gotoxy(1,10);
cprintf("What is your name?");
textcolor(WHITE);
textbackground(BLUE);
xreadln(20,10,40);
strcpy(namestr,answer);
.
.
}

Performance of example:
At 1,10, "What is your name?" appears on the screen. At
the end of this line a cursor appears and the user is
expected to type a name. The user's text will be white and
the background color will be blue. The user cannot type
beyond 40 characters. When the user presses [Enter] or [Esc]
or clicks a mouse button, the program ends.

*************************************************************
void xreadlng(int x,int y, int h) - function

Usage: Used internally by the Magic library. Direct use of
this function is not recommended.

Description: Called by xreadln() when in a graphics mode.

*************************************************************
int zx - Global Variable

Usage: /* example */ px = zx

Description:
This global int variable declared in MAGIC.H is used to
keep track of the maximum horizontal resolution of the screen
in the currently selected graphics mode. If the mode is
changed with cgavideo(), hercvideo(), bestvideo(), etc, zx is
also updated.

Considerations:
Zx is equal to getmaxx(), but faster.

See also:
zy {Magic} getmaxx() {Borland}

Example:
#include
#include
void main() {
magic_setup();
bestvideo();
settextjustify(CENTER_TEXT,CENTER_TEXT);
outtextxy(zx / 2, zy / 2, "test");
waitforuser();
cleanup();
}

Performance of example:
A string of text is centered on the graphics screen, no
matter what graphics mode the current computer is using.
*************************************************************
int zy - Global Variable

Usage: /* example */ py = zy

Description:
This global int variable declared in MAGIC.H is used to
keep track of the maximum vertical resolution of the screen
in the currently selected graphics mode. If the mode is
changed with cgavideo(), hercvideo(), bestvideo(), etc, zy is
also updated.

Considerations:
Zy is equal to getmaxy(), but faster.

See also:
zx {Magic} getmaxy() {Borland}

Example:
#include
#include
void main() {
magic_setup();
bestvideo();
settextjustify(CENTER_TEXT,CENTER_TEXT);
outtextxy(zx / 2, zy / 2, "test");
waitforuser();
cleanup();
}

Performance of example:
A string of text is centered on the graphics screen, no
matter what graphics mode the current computer is using.

*************************************************************

ADVANTAGES OF HAVING THE SOURCE CODE:

* With the easy-to-understand source code, you can make
modifications to customize it exactly to your needs.

* You can learn many 'secret' or hard to find C programming
techniques.

* Even though MAGIC.LIB takes little room and runs quite
fast, you can strip down MAGIC.LIB for even greater
efficiency.

* You can use portions of the source code as a frame work,
changing this or that, inserting your own code, and build
amazing programs of your own invention.

* You can easily build a tight object-oriented version of
C-Magic when you have the source code. This will enable neat
tricks like creating several instances of pop() or related
functions in graphics modes and be able to have several
layers of pop-ups (within RAM limitations, of course)

* You can look at my approach to programming and laugh,
possibly commenting under your breath about how you would
have done it better. Then, with the source code in your
possession, you can do it better!

Notice: This is shareware. Feel free to copy and distribute
the shareware version without modification. If you use any
portion of the Magic library in your programs then
registration is a legal necessity. Send $39.95 to Another
Company. Complete, well-documented easy-to-understand source
code is available. For registration + registration, send
$79.90.

Send US funds drawn on a US bank to:

Another Company
P.O. Box 298
Applegate, OR 97530
USA
503-846-7884

Please include $3 for postage inside the USA, $5 for
postage to Canada, or $7 for postage to all other countries.

If you require 3.5" disk size, please add $1.00.

Even though this seems quite bug-free to me, it is version
1.5 and you may find a surprise or two. I make no warranty.
Thanks for trying this software. Please feel free to submit
bug reports, which I will turn into fixes in later versions.

- Jeff -
September 2, 1992

P.S.
If you require technical assistance, you can try to phone me
at 503-846-7884. Best bet is 9-5 weekdays, but I'm not always
available.

P.S. #2
Since you are going to write some wonderful programs, you
might as well start making money with them! You won't have to
work in an office doing programming for someone else. You
can write exactly the kind of programs you want to write, and
make money at home!

The 'secret' is shareware. Does it work? You bet! You
can easily have a small success, making some extra spending
money each month, or with some practice, you can have a
larger success!

ANOTHER COMPANY shows you everything. Besides our own
shareware successes, including WRITER'S DREAM, BICYCLE
TUNE-UP AND REPAIR, MONEY, THE MULTIMEDIA WORKSHOP, BETTER
EYESIGHT, WHAT'S IN THAT BOX? and THE UNIVERSAL CONVERTER,
we have researched the shareware market, we have interviewed
other shareware authors and have learned about all sides of
the rapidly expanding shareware business.

We show you how to write programs that capture the
public's interest, how to make sure your customers
'register', and how to get money by other means through your
shareware. We show you more. We show you frequency charts
indicating which types of programs sell best, we offer
suggestions for programs as yet unwritten, we talk about
your on-disk instruction manuals, we even show you how to
write user-friendliness into your programs.

Can you succeed without SUCCESS WITH SHAREWARE? Yes!
But why do it the hard way? We have learned all the
super-professional approaches, the pitfalls and the
shortcuts. We'll tell you all about it, and then instead of
stumbling around for the first couple of years, you'll be
a professional from the start!

To get your copy of SUCCESS WITH SHAREWARE! (which is not
shareware, itself - only available from Another Company),
send $29.95. Please add $1.00 if you need 3.5" disk size.

Please include $3 per order for postage within the USA, $5
to Canada or $7 to all other countries.

You can order products by writing your order on plain paper,
or by printing the included ASCII file called Order.frm, or
by phoning 1-503-846-7884, generally weekdays between 9 and
5, west coast time.