"What's this, a totally free applet?", you ask? Well, no, not exactly. This applet is E-Mail-ware, which means that in exchange for the time and trouble it took to write, debug (well, we'll see!), and set up this page, you agree to send the author an e-mail, just a short sweet little note with the address of the page on which you are using it, and of course, all praises and accolades you find appropriate!!! (The latter are, of course, optional, and may be replaced by curses and jeers if you find you have trouble using the program... though keep in mind the price you paid as you belittle the author's herculean efforts!  : )

Reminds me of a particularly clever old shareware nag : "If you enjoyed this program, please send ten dollars. If you hated it, send five!"  : )

Step By Step Instructions:

First, download the files.

If you're reading this, you must have successfully completed step 1 !  : )
If you downloaded the individual files, rename Tutorial.ht to Tutorial.html, and Sorcery.ht to Sorcery.html. If you downloaded the zip file, these html files are already correctly named.

Second, place the five files in a single directory, and open the Tutorial.html file to begin setting up your own applet tag, using the Sorcerer's Color Selector applet, which will open on the Tutorial page, to select your text colors.

Third, after renaming the original Sorcery.html file to another name (in case you want to refer to its applet tag, for help with writing your own ), modify the applet tag PARAMS to your own text and colors. Using the existing Sorcery.html file makes it easy to switch back and forth between the tutorial and the applet as you make modifications, then view the results.

Finally, when your messages are perfected, copy the applet tag into the html file for the page on which you want the applet to be displayed. Then upload these files into the *same* directory in your server space:

RolyPolyBall.class

IDFrame.class

Your own page's html file, containing the applet tag.

Be sure the files in your server space are named *exactly* as they appear here. Java is case-sensitive, and misspelled or mis-capitalized file names will prevent the applet from loading.

---

A Brief HTML Applet Tag Tutorial for the 'Sorcerer's Sphere' Applet

NOTE: For a more extensive tutorial covering use of the applet tag as well as techniques for positioning the applet itself on your web page, refer to the online sample chapter from "Teach Yourself Java In 21 Days", by Laura Lemay and Michael Morrison, at http://www.lne.com/Web/Java/ch08_TOC.html

Java applets are loaded into a web page by means of the APPLET tag within your page's html file. Included within the APPLET tag for the'Sorcerer's Sphere' applet are the following items:

CODE attribute:

Despite requiring two classes to run, only the "main" class, RolyPolyBall.class, is cited in the CODE attribute. Use of this attribute in this manner *requires* that both of the class files, and your html file that "calls" the applet, be in the *same* directory in your server space.

HEIGHT and WIDTH attributes:

These two attributes control the size of the applet "window" itself (the grey box which appears as the applet begins to load). In order to maintain some minimum standard of appearance in the applet's rendering, some size and proportion limits have been imposed. Any invalid combination of HEIGHT and WIDTH will result in the applet's printing an advisory error message and stopping. (The "ideal" (during development) size for this applet is a WIDTH/HEIGHT ratio of 3 to 2.)
 
Here are the valid applet size and proportion ranges:

Minimum Height:

The HEIGHT attribute must be no less than 100.

Maximum Proportion:

The ratio of WIDTH to HEIGHT may be no greater than 3 to 1, or 3.0 (divide WIDTH by HEIGHT).

Minimum Proportion:

The minimum ratio of WIDTH to HEIGHT depends on the applet's HEIGHT:

HEIGHT >= 100 and HEIGHT < 150 :

The minimum ratio of WIDTH to HEIGHT for this range of heights is 1.5

HEIGHT >= 150 and HEIGHT < 200 :

The minimum ratio of WIDTH to HEIGHT for this range of heights is 1.0

HEIGHT >= 200 and HEIGHT < 250 :

The minimum ratio of WIDTH to HEIGHT for this range of heights is 0.8

HEIGHT >= 250 :

The minimum ratio of WIDTH to HEIGHT for this range of heights is 0.75

Maximum HEIGHT and WIDTH :

There are no constraints on the maximum size of the applet. However, the larger the applet size, the *slower* the animation will run !

PARAM tags:

The applet PARAM (for 'parameter') tags are the means by which you set up the applet to display your own messages. Each PARAM consists of a NAME and its VALUE. Each parameter NAME *must* be spelled exactly as it appears in these examples. Notice there are *no* spaces in any of the PARAM names! Missing or misspelled parameter names and/or values, or values which are invalid, will either cause the applet to print an advisory error message and stop, or use the pre-programmed default values. The text you enter for each of these attributes should be surrounded by quotes.

No PARAM tags added:

The applet can be used simply as an animation, with no message screens, just by *not* including any PARAM tag within the applet tag.

Here's the list of parameters for setting up the 'Sorcerer's Sphere':

NumberOfMessageScreens:

This is the *total* number of individual message screens you wish to display. This PARAM is the most important in that any misspelled or invalid input will cause the program to run either as though there are *no* message screens to be displayed, or with fewer message screens than you expect. Each message screen is numbered, beginning with 1 for the first (!), and that title precedes each of the elements of that screen. For example, Screen1 includes Screen1NumberOfLines, Screen1Line1Color and Screen1Line1Text. Each of the PARAM names for Screen2 are preceded by the title Screen2, etc.
 
The limit on the total number of message screens you can use is likely system- and memory-capacity-dependent. Running the applet in MSIE3 under Windows95 on a 16MbRam Pentium system, the applet stops running at just over 1,250 characters (total for all message screens). (This is also with the CD player going and a number of text editors open as well.) As fascinating and awe-inspiring as I realize this applet's graphics might be ;>, *nobody's* gonna stick around long enough to read *that* many messages!, and putting that many characters on *one* message screen slows the program down to a crawl anyhow! The bottom line is that you should use some restraint in the length and total number of messages you try to display, and in that case, you shouldn't run into any memory-shortage problems (which are relatively benign, at least in MSIE, which simply stops displaying *anything* in the applet window if too many characters are requested via the html file.)

Screen1NumberOfLines:

(...and Screen2NumberOfLines, etc. ) This is the *total* number of individual lines which are displayed on the current message screen. Missing, misspelled, or invalid input will cause an appropriate error message to be printed.

Screen1Line1Color:

Each individual line of text on a message screen can be set to one color. Each of the 255 colors in the programmed palette is identified by a number. To facilitate the selection of your text color choices, a utility applet, SorcColorSelector.class, is included below. Use the mouse cursor to point to the desired color, and its corresponding palette number will be displayed.

Java applet running here...

The Sorcerer's Color Selector

Using a color number not in the inclusive range 0 to 255 will cause that line of text to be displayed in the default white. If you *want* white text, use a number outside that range. A missing or misspelled PARAM NAME for a Screen*Line*Color will cause that line to be displayed in the default white.

Screen1Line1Text

This PARAM name identifies the MessageScreen1 first line, and the VALUE should be set to the text you want displayed on that first line.
 
Here are some items to consider while trying to arrange your message screen:

The Font:

There is a limited selection of characters which can be displayed in your messages:
ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789$!.?,-'
 
The font is a fixed-width font, meaning every character spans the same 8 pixels wide by 14 pixels high space. Any unsupported character included in your text line will leave a blank space in the text line display. (Later versions of this applet might support a larger, more attractive font!)

Number of Text Lines Per Message Screen:

The program checks the number of lines for each message screen you include in your html file, and prints an error message for any screen for which there are too many lines to be displayed at the minimum 14 pixels per line.

Number of Characters Per Text Line:

The font size on each individual line is automatically scaled in this way: First, a maximum font size is calculated to display all the lines for this message screen at their largest possible size (up to the maximum number of lines at the minimum font size). Second, each individual line is scaled to use the largest font (up to the maximum font size) that will allow the line to fit onscreen. Each text line is automatically centered.
 
There is *no* error checking for individual lines fitting completely onscreen at the minimum font size. You'll have to test for this yourself visually. (This allows the following technique...)

Forcing a Smaller Font Size For a Line:

In cases where you wish to prevent individual lines from scaling to their largest possible size, such as short lines of less-significant text that would otherwise be larger than the surrounding, longer and more important lines... add 'unsupported' characters before and after the text line. Unsupported characters are any which do not appear in the list of supported font characters, above. The * character is one possibility.
 
By adding more or fewer space-creating, unsupported characters to the beginning and end of your text line, you can adjust the font size of a text line from the maximum font size for that message screen, down to the minimum font size.
 
Spaces *within* the text line are no problem, and you can add these internal spaces to arrange your text on an individual line as needed, using the normal spacebar.
 
(Because of the inconsistency in handling of leading and trailing spaces around text in the two test platforms, it is preferrable to use an unsupported character rather than a space. For you Java programmers, it's interesting to know that, while appletviewer passes leading and trailing spaces around parameter strings into the program unchanged, MSIE automatically trims leading and trailing spaces from parameter strings! )

Arranging Text Line Vertical Spacing:

By adding text lines of all unsupported characters, you can adjust the vertical spacing between visible lines. Since the number of characters in the text line of unsupported characters controls the font size for that line, and hence the vertical space it occupies, you can arrange your visible text lines by varying the size of the "invisible" lines. No LineColor Param needs to be included for "invisible" lines.

---

Terms of Use:

The 'Sorcerer's Sphere' Text Messager Java Applet, and all associated files, are Copyright W.J.Baker, January 8, 1998. All Rights Reserved. This software may not be decompiled or modified in any way. Use of this software means that you understand and agree that the author is not responsible in any way for any damages that may be caused by its use, or from any subsequent problems or damages associated with its use, and that you accept all responsibility for its use and the messages which you display with it. USE OF THIS APPLET ON COMMERCIAL WEBSITES, OR TO ADVERTISE WEBSITES WHICH EITHER CHARGE FOR THEIR USE, OR OFFER PRODUCTS FOR SALE, IS STRICTLY PROHIBITED.

---

Return to the Applet