TextScroll-HOWTO

Version 0.3
Kevin Swan
Last modified: 01 Apr 1998

Introduction

This document is intended to give you complete step-by-step instructions on how you can use the TextScroll applet in your own web pages, and modify it to look differently. The TextScroll applet is completely documented at http://dragon.acadiau.ca/~013639s/java/TextScroll/.

Note that there are two versions of this applet. There is a Java 1.1 version, which is the standard one, called TextScroll. There is also a version written for Java 1.0, which runs in more browsers, since many people still haven't upgraded to Java 1.1-compliant web browsers. This Java 1.0 version is called TextScroll_1_0. This is the version I will discuss in this HOWTO. Its documentation is located at http://dragon.acadiau.ca/~013639s/java/TextScroll/Java-1.0/.

The two different versions are functionally identical. They both support exactly the same directives. The only differences are that the Java 1.1 version uses a MouseListener to handle clicking events, while the Java 1.0 version uses the action() method. Also, the Java 1.1 version uses reflection to handle directives, while the Java 1.0 version uses string comparison, making it a little larger. As far as the users and web authors are concerned, they are exactly the same, except the Java 1.0 version will work for more people.

How it Works

To use TextScroll, all you have to do is basically two things:

1. Put the <APPLET> tag in the page you want to have TextScroll in.
2. Write the script file TextScroll will display, and tell TextScroll where this file is, using a <PARAM> tag in the <APPLET> tag.

The applet goes out with the web page, then looks at the <PARAM> tag you've supplied with that page that holds the "data" value. This tag tells the applet where to get the text file from that you want it to display. You do not include text in the HTML page for TextScroll to display, it must be in another file. You write a file and save it as plain text. Say you have a web page called index.html. You want to have the TextScroll applet in it. You want it to scroll the text "Hello World!". So, in your index.html file, you include the following tag:

  <APPLET CODE="TextScroll_1_0.class"
          WIDTH=100
          HEIGHT=200>
    <PARAM NAME="data"
           VALUE="hello.txt">
  </APPLET>

Since no CODEBASE was specified, you must put the file TextScroll_1_0.class in the same directory as index.html. We could have put it somewhere else and specified a CODEBASE. Say you have a directory on your web site where you keep all your applets. Perhaps this directory is http://some.host.somewhere/~yourusername/applets/. Then, you could put the file TextScroll_1_0.class in that directory, and modify your applet tag as follows:

  <APPLET CODEBASE="http://some.host.somewhere/~yourusername/applets"
          CODE="TextScroll_1_0.class"
          WIDTH=100
          HEIGHT=200>
    <PARAM NAME="data"
           VALUE="hello.txt">
  </APPLET>

Now you can use this tag in all your web pages, but you will still have to have a file called hello.txt in the same directory. Let's consider the data file now.

hello.txt in this example is the text file containing the text you want to display, as well as the directives. If all we want it to display is "Hello World!" over and over, all we would put in the file hello.txt is "Hello World!" This file would have to be in the same directory as the HTML file displaying the applet. However, in TextScroll versions 2.4 and above, you can specify a complete URL for the location of the script file. So, say you have another directory where you store all your script files on your web site, and the URL of the script file hello.txt is http://some.host.somewhere/~yourusername/scripts/hello.txt, then you could use the following tag in ANY web page that you wanted to have a scrolling "Hello World!" in:

  <APPLET CODEBASE="http://some.host.somewhere/~yourusername/applets"
          CODE="TextScroll_1_0.class"
          WIDTH=100
          HEIGHT=200>
    <PARAM NAME="data"
           VALUE="http://some.host.somewhere/~yourusername/scripts/hello.txt">
  </APPLET>

This will work regardless of where the web page containing this tag is. Note, however, that the server named in the CODEBASE and the server listed in the PARAM NAME="data" tags must be the same server, since Java applets can only open network connections with the server they came from. The pages containing this tag can be anywhere, they do not have to be on the same machine.

Writing the Text File

This section will discuss what to put in this text file. The text file you name in the <PARAM NAME="data" VALUE="..."> tag must be a plain ASCII text file. The data is read one line at a time. Each line the applet reads is treated one of two ways, depending on the first two characters of the line:

1. If the first two characters are "^^", the line is treated as a directive, discussed later. For clarification, that string is a pair of carets, the characters resulting from a SHIFT-ed 6 on IBM keyboards.
2. Otherwise, the line is treated as a line of plain text, and is displayed to the screen. Note that TextScroll does not yet support automatic line wrapping, so you must ensure that the text will fit in the applet area. The applet will happily write text off the edge of the applet, where it will not be seen.

Directives

Directives allow you to control the behaviour of the applet from the text file. It is basically a way to invoke a method call in the applet. When the applet is displaying text, it uses several attributes and flags to determine how it will display, such as whether or not it should center the text it is displaying, what font to display the text in, as well as foreground and background colors. All supported directives are documented in the table below.

This feature is best illustrated with an example. Consider the following text, which we would save in a file called plug.txt:

^^setURL (http://dragon.acadiau.ca/~013639s/java/TextScroll/Java-1.0/)
^^setSpeed(93)
^^setBackgroundColor(255,30,30)
^^setForegroundColor(255,255,255)
^^setFontFace(SansSerif)
^^setFontSize(12)
^^setCenter (true)
Its Elegant.
^^pause(1500)
^^setBackgroundColor(30,130,30)
^^setForegroundColor(255,255,255)
Its Versatile.
^^pause(1500)
^^setBackgroundColor(30,30,130)
^^setForegroundColor(255,255,255)
Its Free.
^^pause(1500)
^^setBackgroundColor(255,255,255)
^^setForegroundColor(0,0,0)
^^setCenter (false)
TextScroll  -- http://dragon.acadiau.ca/~013639s/java/TextScroll
^^pause(2500)

Lets examine this line-by-line.

1. setURL (http://...)

   This sets it so when the user clicks on the applet, it loads the given URL into the page, just as if the user clicked on a link.

2. setSpeed(93)

   This sets the scroll speed to 93, out of a possible 100, with 100 being the fastest and 1 being the slowest.

3. setBackgroundColor(255,30,30)

   This sets the background color to a shade of red. You must specify decimal integer RGB values for this method call.

4. setForegroundColor(255,255,255)

   This sets the foreground color to white.

5. setFontFace(SansSerif)

   This sets the font the applet will use to display text to SansSerif.

6. setFontSize(12)

   This sets the font size applet will use to display text to 12 point.

7. setCenter(true)

   This sets the alignment to centering. All text following this method call will be centered, until a call to setCenter(false) is made.

8. Its Elegant.

   This is the first line of actual text to be displayed.

The rest are easy to figure out based on this first set. The resulting applet looks like this:

Table of Directives

setSpeed (int)	Sets the scroll speed to the given integer. The scroll speed must be between TextScroll.MIN_SPEED (1) and TextScroll.MAX_SPEED (100). If it is not, then the speed is left unchanged.
pause (int)	This causes the applet to pause scrolling for the given number of milliseconds.
pause ()	This causes the applet to pause scrolling until the user clicks the text area.
setForegroundColor (int,int,int)	Sets the foreground color to the given RGB value. If the given parameters do not form a legal RGB value, the current foreground color is left unchanged.
setBackgroundColor (int,int,int)	Sets the background color to the given RGB value. If the given parameters do not form a legal RGB value, the current background color is left unchanged.
setFontFace (String)	Sets the font face to use to the given String. This should be one of: Serif SansSerif Monospaced
setFontSize (int)	Sets the size of the font to use to the given integer.
setCenter (boolean)	Sets the centering flag. If the given boolean is true, then all subsequent text is centered, until the directive is invoked with a false value.
setBold (boolean)	Sets the bold flag. If the given boolean is true, then all subsequent text is printed in bold style, until the directive is invoked with a false value.
setItalic (boolean)	Sets the italic flag. If the given boolean is true, then all subsequent text is printed in italic style, until the directive is invoked with a false value.
setInset (int)	Sets the value of the inset, or how many pixels in to print text.
setURL (String)	Sets the URL of the page to be loaded when the applet is clicked on. The String can also be "null" to set the applet so that when the user clicks on it, it simply toggles the scrolling on and off.

If you have any suggestions for improvements on this HOWTO, please let me know by emailing me at [email protected]. I hope this document is helpful to you, and gets you up and running with TextScroll.