TextScroll-HOWTO
Version 0.7
Kevin Swan
Last modified: 15 Dec 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/. This document describes the features available in TextScroll version 2.8.3.

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.class"

          WIDTH=100

          HEIGHT=200>

    <PARAM NAME="data"

           VALUE="hello.txt">

  </APPLET>

Since no CODEBASE was specified, you must put the file TextScroll.class (and the other 3 .class files) 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.class in that directory, and modify your applet tag as follows: 



  <APPLET CODEBASE="http://some.host.somewhere/~yourusername/applets"

          CODE="TextScroll.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 as the HTML file. Let's consider the data file now.

If you don't know what a CODEBASE is, just put the 4 .class files in the same directory as the .html file that uses them.

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.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.

That's Nice, Now Walk Me Through It

If you really don't know much about web sites and Java applets, this is the section for you. These are the step-by-step instructions for getting the applet up and running.

  1. Decide on a page you want to put the TextScroll applet in.
  2. Place all the necessary applet class files in the same directory as the HTML file you wish to have the applet in. You need 4 files:
    1. DataLoader.class
    2. DirectiveManager.class
    3. LineWrapManager.class
    4. TextScroll.class
  3. Write the text file to display. See the section, Writing the Text File for more detailed information on this. For now, just create a plain text file. In this file, just put one line of text, "Hello world!" Save this file as hello.txt.
  4. Add the <APPLET> tag to the web page. It will look like this: 

    

        <APPLET CODE="TextScroll.class" WIDTH=200 HEIGHT=100>

          <PARAM NAME="data" VALUE="hello.txt">

        </APPLET>

That's it. Once you've done that, you will have the following in your web page:

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. Versions 2.6 and above support automatic line wrapping, so you don't need to worry about making sure your text doesn't run off the side of the applet, it will do that itself. Newlines will be ignored, unless two or more occur in a row. This means you can't specify when to start a new line, but you can specify when to start a new paragraph. The easy way to remember it is a single newline by itself is converted to a space. Two or more newlines in sequence are treated as newlines.

Directives

First of all, what is a "directive?" The TextScroll applet operates by loading a plain ASCII text file over the network and displaying its contents. Part of the applet's strength comes from the fact that it can be modified during runtime with extreme flexibility. By embedding directives in the text file the applet is to display, the web developer can alter the way their text will appear in the applet. Directives are the commands embedded in the text file. Since they directly correspond with the methods the applet publishes with the same names, they can almost be though of as method calls.

How does the applet determine what is text is should display, and what is text it should try to interpret as a directive call? Directive calls in the text file are indicated by lines beginning with two caret symbols (^^), that is, the character resulting from a "Shift"-ed 6 on IBM keyboards, inserted twice.

If you wanted to just display "Hello world!" in TextScroll, you would create a text file containing the following: 



Hello world!

When TextScroll displayed this text file, it would use all the default settings, and scroll it at a comfortable speed in black text on a white background. However, what if you wanted to change it so the text were blue? There are two ways to do this:

  1. By including the following <PARAM> tag in the HTML document containg TextScroll: 

    

         <APPLET CODE="TextScroll.class" WIDTH=100 HEIGHT=200>

           <PARAM NAME="foreground" VALUE="0,0,255">

         </APPLET>

    This will set the initial foreground color of all your text to a bright blue.

  2. Alternatively, you could specify the text color by modifying your text file. When we last looked at it above, all it contained was: 

    

      Hello world!

    To tell TextScroll we want the text to be blue, we could use the setForegroundColor directive. Now, the contents of our text file would be: 

    

      ^^setForegroundColor (0,0,255)

      Hello world!

    Using setForegroundColor allows you tighter control over the colors, since you can call it multiple times in the same file, and change the colors throughout the document.

Let's look at a more detailed example. The following illustrates several of the directives. Assume we have a text file containing the following text: 



^^setURL (http://dragon.acadiau.ca/~013639s/java/TextScroll/)

^^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)

Here's how the applet will behave when it reads this file. 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:

Complete list of Directives

The following is a complete list of supported directives for TextScroll, as of version 2.8.3.

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. Note that this might cause a conflict if you have a URL set with setURL (). If you do have a URL set with setURL () and include the pause () directive, then if the user clicks on the applet, the URL will be loaded, and scrolling will never resume. Be extra careful when mixing this directive and setURL ().
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. This is the same as setRightForegroundColor.
setLeftForegroundColor (int,int,int) Sets the foreground color for the left pane to the given RGB value. If the given parameters do not form a legal RGB value, the current foreground color for the left pane is left unchanged. Panes are discussed below, in the section titled Panes.
setRightForegroundColor (int,int,int) Sets the foreground color for the right pane to the given RGB value. If the given parameters do not form a legal RGB value, the current foreground color for the right is left unchanged. Panes are discussed below, in the section titled Panes.
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. This is the same as setRightBackgroundColor.
setLeftBackgroundColor (int,int,int) Sets the background color for the left pane to the given RGB value. If the given parameters do not form a legal RGB value, the current background color is left unchanged. Panes are discussed below, in the section titled Panes.
setRightBackgroundColor (int,int,int) Sets the background color for the right pane to the given RGB value. If the given parameters do not form a legal RGB value, the current background color is left unchanged. Panes are discussed below, in the section titled Panes.
setFontFace (String) Sets the font face to use to the given String. This should be one of:
  • Serif
  • SansSerif
  • Monospaced

This is the same as setRightFontFace.

setLeftFontFace (String) Sets the font face to use in the left pane to the given String. This should be one of:
  • Serif
  • SansSerif
  • Monospaced

Panes are discussed below, in the section titled Panes.

setRightFontFace (String) Sets the font face to use in the right pane to the given String. This should be one of:
  • Serif
  • SansSerif
  • Monospaced

Panes are discussed below, in the section titled Panes.

setFontSize (int) Sets the size of the font to use to the given integer. This is the same as setRightFontSize.
setLeftFontSize (int) Sets the size of the font to use in the left pane to the given integer. Panes are discussed below, in the section titled Panes.
setRightFontSize (int) Sets the size of the font to use in the right pane to the given integer. Panes are discussed below, in the section titled Panes.
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. This is the same as setRightCenter.
setLeftCenter (boolean) Sets the centering flag for the left pane. If the given boolean is true, then all subsequent text in the left pane is centered, until the directive is invoked with a false value. Panes are discussed below, in the section titled Panes.
setRightCenter (boolean) Sets the centering flag for the right pane. If the given boolean is true, then all subsequent text in the right pane is centered, until the directive is invoked with a false value. Panes are discussed below, in the section titled Panes.
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. This is the same as setRightBold.
setLeftBold (boolean) Sets the bold flag for the left pane. If the given boolean is true, then all subsequent text in the left pane is printed in bold style, until the directive is invoked with a false value. Panes are discussed below, in the section titled Panes.
setRightBold (boolean) Sets the bold flag for the right pane. If the given boolean is true, then all subsequent text in the right pane is printed in bold style, until the directive is invoked with a false value. Panes are discussed below, in the section titled Panes.
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. This is the same as setRightItalic.
setLeftItalic (boolean) Sets the italic flag for the left pane. If the given boolean is true, then all subsequent text in the left pane is printed in italic style, until the directive is invoked with a false value. Panes are discussed below, in the section titled Panes.
setRightItalic (boolean) Sets the italic flag for the rightpane. If the given boolean is true, then all subsequent text in the right pane is printed in italic style, until the directive is invoked with a false value. Panes are discussed below, in the section titled Panes.
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. text. Note that the URL must be a full URL, including the "http://" at the beginning.
setURL (String, String) Sets the URL of the page to be loaded when the applet is clicked on, BUT it will be loaded in the named frame, not the same frame as the applet. The two arguments are:
  1. The name of the frame to load a URL in when the applet is clicked on. If this is "null" or "_top" then it will load the target URL in the whole browser window, destroying all frames. If a frame name is a name not associated with a frame on the page, a new browser window is opened and the target URL is loaded when the user clicks on the applet.
  2. The String URL. This is the same as in setURL (String), documented above. If it is "null", then when the user clicks on the applet, it will simply toggle scrolling off and on. Note that the URL must be a full URL, including the "http://" at the beginning.

This directive is best illustrated with some examples.

  1. Say you had a page made up of two frames, "left" and "right." You are running TextScroll in the left frame, and you want it so when people click on the applet, it loads the pages in the right frame. You would use directive calls in your text file similar to these: 

    

                ^^setURL (right, http://www.news.com)

                ^^setURL (right, http://www.cnn.com)

    This way, when the user clicks on your applet in the left frame, the URL is displayed in the right frame, while the left frame stays, still displaying the applet.

  2. Perhaps you want to open a new window to display your source code, and you want the browser displaying the page containing your applet to stay open. You could use: 

    

                ^^setURL (new, http://my.host.com/~username/path/file1.java)

                ^^setURL (new, http://my.host.com/~username/path/file2.java)

    If these are used in TextScroll while TextScroll is on a page that doesn't use frames, or simply doesn't have a frame named "new" then it will open a new browser to display your code.

  3. Finally, maybe you have a page containing frames, and TextScroll is in the left frame. You want it so when a user clicks the applet, it will display the target URL in the whole window, destroying the frames. You would use directives similar to the following: 

    

                ^^setURL (null, http://www.news.com)

                ^^setURL (_top, http://www.news.com)

                ^^setURL (http://www.news.com)

    All three of those directive calls have the same effect. They will all load the web site www.news.com in the browser, destroying all your frames.

A demo page has been written to demonstrate this directive in action.

setLeftText (String) Sets the text to display in the left pane to the given String.

Parameter tags

This section describes the legal <PARAM> tags permitted to be used with the TextScroll applet. This information is current as of version 2.8.3. Parameter tags are put in the HTML file containing the applet, in between the <APPLET> tag and the </APPLET> tag. Here is an example of how you would use these parameter values to specify that the TextScroll applet should use the text file called "textfile.txt" in the same directory as the HTML file, and refresh it every time it has been displayed 5 times. 



<APPLET CODE="TextScroll.class" WIDTH=200 HEIGHT=400>

  <PARAM NAME="data" VALUE="textfile.txt">

  <PARAM NAME="refresh" VALUE="5">

</APPLET>

The following table is taken from the javadoc-generated documentation for TextScroll.

Name Description Example
fontface The style of Font to use. It must be a type supported by Java. If an invalid font face is specified, SansSerif will be used. SansSerif is also the default font face. Permitted values are:
  • SansSerif
  • Serif
  • Monospaced

 

<PARAM NAME="fontface" VALUE="SansSerif">
fontsize The size of Font to use. If an invalid size is specified, the default will be used. The default font size is 10. <PARAM NAME="fontsize" VALUE="12">
speed The speed of scrolling to use. Valid values are all numbers from TextScroll.MIN_SPEED (1) to TextScroll.MAX_SPEED (100), with TextScroll.MIN_SPEED being the slowest and TextScroll.MAX_SPEED being the fastest. The default is TextScroll.DEFAULT_SPEED (70). <PARAM NAME="speed" VALUE="65">
data The name of the datafile to use. In versions 2.4 and above, you can use a complete URL in this parameter if you wish. If the value of this parameter starts with "http", it tries to create a new URL from the string. Otherwise, it treats it as a relative URL from the location of the HTML document containing the applet. <PARAM NAME="data" VALUE="scroll.txt">
foreground The foreground color for the applet. This will be the color of the text. The default is white. It must be a trio of integer values which make up a legal RGB color value. Each integer value must be between 0 and 255, inclusively. The example sets the foreground color to a shade of red. <PARAM NAME="foreground" VALUE="144, 32, 32">
background The background color for the applet. The default is black. It must be a trio of integer values which make up a legal RGB color value. Each integer value must be between 0 and 255, inclusively. The example sets the foreground color to a light blue. <PARAM NAME="background" VALUE="224, 224, 255">
refresh This indicates that the applet should re-request the data from the server after the text has been repeated n times, where n is the integer argument to this parameter. The example to the right will reload the text data after it has completely displayed 3 times. Note that this is simply when it starts to load the data again. The data will most likely not be available instantaneously, so it will display the current data again before replacing it with the new data. This means it might actually display 4 or even 5 times before you'll actually see the new data. The benefit of this is that your data will not be changed in the middle of a presentation, it will only be updated at the end. <PARAM NAME="refresh" VALUE="3">
fgloadcolor This lets you specify what the applet should use for a foreground color while it is loading data. The default is blue. This is the color the "Loading data ..." string will be displayed in. You generally won't have to use this unless you are really concerned about it fitting into your page during loading. The default is blue. It must be a trio of integer values which make up a legal RGB color value. Each integer value must be between 0 and 255, inclusively. The example sets the foreground color to green. <PARAM NAME="fgloadcolor" VALUE="32, 144, 32">
bgloadcolor This lets you specify what the applet should use for a background color while it is loading data. The default is light blue. It must be a trio of integer values which make up a legal RGB color value. Each integer value must be between 0 and 255, inclusively. The example sets the background color to a light green. <PARAM NAME="bgloadcolor" VALUE="224, 255, 224">
wraptext This lets you specify whether the applet should apply automatic line wrapping or not. An argument of true will apply line wrapping, an argument of false will wrap the lines as they appear in the data file. This feature was included for users who want tight control of where lines are wrapped. <PARAM NAME="wraptext" VALUE="false">

Note that most of the parameters can be specified in the text file itself, with the exception of the name of the text file, and the text wrapping. The text wrapping is performed when the data is loaded. Thus, the only mandatory <PARAM> tag is the data tag. Indeed, this is the only one I usually specify, since the data file changes most of the other values several times during the presentation.

Several of these parameters can be prefixed with "left" or "right" to produce the same effect on the specific pane. Panes are described in the next section. If the regular parameter name is used, the right pane is assumed. These extra param tags are:

They configure the obvious parameters.

Panes

Panes is a new feature in 2.8.3. It allows you to mimic the same functionality of the scrollers seen on news sites, with a headline on the left of the applet, possibly in a different font, with a different color scheme, and then a message on the right side of the applet. Here's an example:

You need a Java-capable web browser to see the applet.

As you can see, it is very configurable. Simply specify the width you wish the left pane to be using the "leftwidth" PARAM tag, like this: 



<APPLET CODEBASE="." CODE="TextScroll.class" WIDTH=400 HEIGHT=18>

  <PARAM NAME="leftwidth" VALUE="100">

  <PARAM NAME="data" VALUE="splitplug.txt">

</APPLET>

In your .txt file, you specify the text for the left pane using the setLeftText () directive. You configure the left pane's attributes using the various setLeft...() directives. The text file for the above applet is: 



^^setSpeed(93)

^^setLeftBackgroundColor (255,255,128)

^^setLeftForegroundColor(0,0,0)

^^setLeftFontFace(SansSerif)

^^setLeftFontSize(12)

^^setLeftBold (true)

^^setLeftCenter (true)

^^setLeftText (Overview)

^^setRightBackgroundColor(255,255,255)

^^setRightForegroundColor(0,0,0)

^^setRightFontFace(SansSerif)

^^setRightFontSize(12)

^^setRightCenter (false)

Unlike any other free scroller.

^^pause(1500)

^^setLeftBackgroundColor(224,224,255)

^^setLeftText (Features)

It has over a dozen features.

^^pause(1500)

^^setLeftBackgroundColor(224,255,224)

^^setLeftText (Cost)

Its Free.

^^pause(1500)

^^setLeftBackgroundColor(255,224,224)

^^setLeftForegroundColor(0,0,0)

^^setLeftText (More Info:)

^^setCenter (false)

http://dragon.acadiau.ca/~013639s/java/TextScroll

^^pause(2500)

This is all just one applet. Every time you use it, there is a left pane. However, if you do not specify a width with the "leftwidth" PARAM tag, then it uses the default, which is 0. That is, there is no visible left pane.

Note that there are pairs of directives now, one for the left side, and one for the right. This is because TextScroll permits different settings for most attributes for each side. You can have different fonts on the headline bar than on the main (right) pane. Note that you must be careful with font sizes, or else your headlines could overlap, or go off the edge of the left pane.

Feedback

If you have any suggestions for improvements on this HOWTO, please let me know by emailing me at 013639s@dragon.acadiau.ca. I hope this document is helpful to you, and gets you up and running with TextScroll.

All code and documentation on this page is Copyright (©) 1997 by Kevin Swan. If you wish to use this code and distribute it in other products, please contact the author.

vi
 		Powered