------------------------------
    vTEXT 1.0 JAVA APPLET
Copyright  2000 Luis M. Pabn
     All rights reserved
------------------------------


CONTENTS  
--------

1. Overview 
2. Features 
3. System requirements 
4. Installation 
5. Using vText 
6. Creating contents 
7. External control functions 
8. Recommendations 
9. Contact information 


1. OVERVIEW
-----------

Thank you for your interest in vText. Please read carefully the LICENSE
agreement before using this software. A more detailed information can be
found in the README.HTM file.

vText is a Java applet, that is, a component that runs inside a web brow-
ser. This program allows a controlled visualization of contents consisting
of hypertext and images, so that they can be easily integrated into HTML
documents. Actually, it is a kind of microbrowser that can be embedded into
a web page, simplifying its design and elaboration, as well as increasing
the visual posibilities.

Its small size, the high configurability and the great variety of different
styles, make it a very flexible and compact component. It gathers (and im-
proves) a lot of characteristics that could only be found on separate app-
lets. Among its possible aplications we can mention these:

- Precise text composing in web pages 
- Visualization of long contents is small areas 
- Vertical scrollers (with manual or automatic scroll) 
- News tickers with active links 
- Menus and content navigators 
- Image sliders and banners 
- Dinamic message boards 
- Many other special effects 

If you want to get a real idea of what vText is able to do, don't forget to
take a look at the EXAMPLES directory included in this package. 


2. FEATURES
-----------

vText gathers several and quite interesting features that may help and
simplify the tasks of any web designer, and also can be useful for advan-
ced users and webmasters who want to create more complex effects and beha-
viours. Next parragraphs summarize the main characteristics of the compo-
nent:

- TOTAL APPEARANCE CONFIGURATION. It is possible to control many parameters
  of the visual appearance, such as dimensions, colors, border, title, mar-
  gins, scroll botons and sliders, popup messages, hyperlinks, etc. (up to
  almost 50 parameters).

- CONTENT REPRESENTATION. vText represents the content provided by commands
  or text files, which describe it using a small subset of the HTML langua-
  ge (with some variations and aditions). So, it is possible to specify the
  typography (font, size and style), the colors, the space between lines of
  text, the alignment -including full justified text (as a beta feature)-,
  the appearance and behaviour of links, etc. (more than 40 recognized con-
  trol tags).

- BACKGROUND AND FOREGROUND IMAGES. In adition to the images included in
  the body of the content, you can set a background and foreground ima-
  ges. In both cases, it is possible to configure the position, the repeti-
  tion of a pattern, or their behaviour when the text scrolls. Playing with
  background images and transparencies of foreground images can produce ve-
  ry cool visual effects.

- INTERNAL/EXTERNAL HYPERLINKS AND NAVIGATION. vText works as a microbrow-
  ser that can activate links to Internet pages and resources. The target
  can be any frame or window of the website, but it also can include refe-
  rences to new vText contents, loading and rendering them into the same
  applet. This second type of links is useful when showing several "pages"
  of content without the need of reloading the HTML page.

- VERTICAL SCROLL. If the extension of the content exceeds the dimensions
  of the visible area, the program allows a smooth scroll to be done in se-
  veral ways. The scroll mode can be locked (no movement), can be automa-
  tic, or can be controlled by scroll arrows, by keyboard, by mouse dragg-
  ing, by a lateral slider or even by external scripts. It is possible to
  set the scroll speed and delays in most of the cases.

- DYNAMIC CONTENS AND EXTERNAL CONTROL. The contents can be taken from a
  line parameter or from an external text file. In adition, it is possible
  to set requests to dynamic pages and resourses (such as CGI, ASP, PHP...)
  so that they generate specific contents for vText. On the other way, the
  applet includes some externally accesible functions in order to reload
  the contents or to control the vertical scroll. This functions can be
  called from scripts (JavaScript, JScript o VBScript, for example).

- EXTRA FEATURES. In spite of the small size of the component (aprox.
  17 kb), there are several small details that were included in order to
  get a neat and refined utility. Some examples are the status and popup
  messages, the mouse pointer cursors, and many others. In addition, if
  you purchase a Developer or an ISP license, you receive complete tool to
  easily create vText components, and also the necessary files for vText
  integration with Macromedia Dreamweaver.


3. SYSTEM REQUIREMENTS
----------------------

vText just requires the use of a web browser that supports Java tecnology,
such as the popular Microsoft Internet Explorer or Netscape Navigator. The
program is compiled and compatible with the JDK 1.02 specifications, so it
should run without problems even on some old versions of these browsers.

The only file which is strictly required is vText.class, or its packed ver-
sion vText.jar (recommended). In adition to these files, all your content
archives and images must be available from the web page through the speci-
fied paths and directories.

In order to get the best performance from the component, a 16 or 24 bit co-
lor resolution is recommended. Memory requirements strongly depend on the
size and complexity of contents (see recomendations below).


4. INSTALLATION
---------------

Uncompress the distribution package vText10.zip (if you haven't done it
yet) with a decompression utility such as WinZIP or PKZip. Once you have
done this, you will get, at least, the following files:

vtext.class     Java class containing the applet
vtext.jar       Packed version of the applet
readme.htm      This document
faq.htm         Document containing frequently asked questions about vText
license.htm     License agreement for the current distribution
register.htm    Information about vText licenses and how to purchase
form.txt        Registration form to order new licenses via fax or mail
/examples       Directory containing several examples of use

In addition, if you have purchased a Developer or ISP license, you will
also see the next folders: 

/assistant      Directory of the vText Assistant  
/dreamweaver    Directory of files for Macromedia Dreamweaver integration

vText requires no other installation than just copying the .jar and .class
files into the desired folders of your web project. Then you will be able
to insert the applet into your HTML documents as explained in the next sec-
tion.


5. USING vTEXT
--------------

Once you have put the Java classes on the right place, the next step is to
insert vText into a web page with an APPLET tag. Consult your HTML documen-
tation to get a full description of this HMTL element and its attributes.
In general, you will type something like this:

...........................................................................

<APPLET
  CODEBASE=".."
  ARCHIVE="vText.jar"
  CODE="vText.class"
  WIDTH="256"
  HEIGHT="384"
  HSPACE="0"
  VSPACE="0"
>
  <PARAM NAME="copyright"
         VALUE="Copyright (c) 2000 Luis M. Pabon - http://luis.pabon.com">
  <PARAM NAME="source"
         VALUE="@contenido.vtm">
  <PARAM NAME="bgcolor"
         VALUE="FFC000">
  <PARAM NAME="left"
         VALUE="16">
  <PARAM NAME="right"
         VALUE="16">
  <PARAM NAME="fontname"
         VALUE="Helvetica">
  <PARAM NAME="align"
         VALUE="justify">

... more parameters ...

</APPLET>

...........................................................................

vText admits a lot of parameters to control its aspect and functionalities.
They are described in a table below, but we will first take a look at two
of them, which are specially important. The first one is the copyright pa-
rameter. This is a required parameter, and its value must be exactly the
next character string:

  Copyright (c) 2000 Luis M. Pabon - http://luis.pabon.com  

Don't change this parameter, other way the applet will not work. The second
important parameter is called source, and you can use it to provide the
contents. It can directly privide the contents to vText with a string that
follows the syntax described in the next section. An example of its value
could be:

  This is the message to be painted by <b>vText</b>  

But this is not the most useful case. Usually you'll want vText to display
longer and more complex contents, so it is better to describe them in a se-
parate text file and set a link to it in the source parameter. This is done
with the @ prefix:

  @myfile.txt  

This will cause vText to read the file and parse its contents. The file can
have any name or extension. Even more, the source parameter can also con-
tain links to other Internet resources such as CGI programs, or dynamic pa-
ges (ASP, PHP, ...) which generate the adequate contents for vText. The on-
ly limitation is that the file or resource must be located in the same host
where the applet is (this is due to security limitations of Java applets).

The rest of the parameters are used to describe vText appereance and beha-
viour. Most of them are optional and can also be included inside the BODY
tag of the content description. The next paragraph shows an alphabetically
sorted list of the 47 parameters recognized vy vText 1.0. Please read the
HTML documentation for details.

  vText parameters: align, justify, bgcolor, bgfixed, bgimage, bgpopup,
  bgposx, bgposy, bgrepeat, bgtitle, border, bordercolor, bottom,
  btnscalex, btnscaley, copyright*, fgcolor, fgfixed, fgimage, fgpopup,
  fgposx, fgposy, fgrepeat, fgtitle, fontname, fontsize, fontstyle, hover,
  left, linesp, lnkcolor, right, scrcolor, scrolldelay, scrollmode,
  scrollstep, sldcolor, sldheight, sldwidth, source*, status, titalign,
  titfont, titheight, title, titsize, titstyle, top.

If you have purchased a Developer on an ISP License, your will find the
vText Assistant in your distribution package. This program is a small wi-
zard that will help you in the task of configuring all these parameters.
Also, you may install the files for the integration of vText with Macrome-
dia Dreamweaver. Look into their particular directories to get more de-
tails.


6. CREATING CONTENTS
--------------------

Now that we know how to use the applet in our web pages, let's see how to
create contents for vText. The information (text, images, links, etc.) can
be described with a small and particular subset of HTML tags. If you are
used to the estndar HTML syntax (and even if you aren't), you will find
that creating contents for vText is really easy.

As we have already seen, contents are passed to vText as a text string
(source parameter) or in a plain text file (using the prefix @). Appearance
of the text and special elements is specified with control tags, which are
always delimited by the characters '<' and '>'. The general structure of
the contents is as shown in the next box:

...........................................................................

<TITLE parameters... >Title text</TITLE>
<BODY parameters... >
  ...Contents...
</BODY>  

...........................................................................

The TITLE tag is used to describe the title shown in the applet. It is an
optional tag, but when is present, it must be the first one in the text.
BODY delimites the contents to be shown by vText. This take takes almost
the same parameters as the applet itself, so it is possible to set a diffe-
rent appearance for each content, without reloading the applet.

The next list shows these and other control tags that can be used to des-
cribe vText contents. read the HTML documentation for more details.

  List of vText tags: A (target, href, title, name, color, bgcolor,
  plain), ADDRESS, B, BIG, BODY (applet parameters), BR, CENTER, CITE,
  CODE, DEL, DFN, EM, FONT (face, size, color, bgcolor), HR (width, size,
  color, align), I, IMG (src, border, bordercolor, align), INS, JUSTIFY,
  KBD, LEFT, P, PAUSE (time), PRE, RIGHT, S, SAMP, SMALL, STRIKE, STRONG,
  SUB, SUP, TITLE (align, bgcolor, fgcolor, fontname, fontsize, fontstyle,
  height), TT, U, VAR.

Although some of these tags are synonymous commands and produce the same
result, they were included in order to get a better compatibility when wri-
ting vText contents with a traditional HTML notepad or editor. In addition,
vText is able to recognize special characters described in the HTML way:

  &name; Special characters in their HTML abbreviated form.
  &#dd; Special characters by their decimal Unicode numbers (dd).
  &#Xhh; Special characters by their hexadecimal Unicode numbers (hh).

The best way to learn how vText works is practice. You can start taking a
look at the EXAMPLES directory included in this package, where you will
find a practical explanation of most of these tags and parameters.


7. EXTERNAL CONTROL FUNCTIONS
-----------------------------

* Note *: this can be considered a subject for advanced users. You don't
need to read this section in order to get vText working. Well, in fact,
this matter is not complex at all, but you should better understand all the
previous concepts rather than starting from here.

vText has two public functions that can be accessed from external elements
such as scripts (Javascript, VBScript), other Java applets, Flash movies,
etc. These functions are called scroll and reload, and they are used to
control the vertical scroll and the contents of the applet.

the scroll function takes a character string as an argument. The text of
the string specifies the scroll command to apply. Valid commands are:

  scroll("Up"). Starts unitary scroll up. 
  scroll("Down"). Starts unitary scroll down. 
  scroll("Stop"). Stops the scroll. 
  scroll("PgUp"). One page up. 
  scroll("PgDown"). One page down. 
  scroll("Home"). Goes to the top of the content. 
  scroll("End"). Goes to the bottom of the content. 

Let's see an example of how this works. Supose we have included a vText
applet in our web page with this HTML code:

...........................................................................

<APPLET NAME="MyApplet"
        ARCHIVE="vText.jar"
	CODE="vText.class"
	WIDTH="256" HEIGHT="384">
  ... etc. ...
</APPLET>

...........................................................................

It is very important the value of the NAME argument in the APPLET tag, be-
cause we will use this name when referencing the applet. Now, somewhere in
the same HTML code (or in other frames), we could control the scroll with
Javascript calls like these:

...........................................................................

<INPUT TYPE="button" VALUE="Go up"
  ONMOUSEDOWN="javascript:document.MyApplet.scroll('up');"
  ONMOUSEUP="javascript:document.MyApplet.scroll('stop');">
<INPUT TYPE="button" VALUE="Go down"
  ONMOUSEDOWN="javascript:document.MyApplet.scroll('down');"
  ONMOUSEUP="javascript:document.MyApplet.scroll('stop');">
<INPUT TYPE="button" VALUE="Page up"
  ONMOUSEDOWN="javascript:document.MyApplet.scroll('pgup');">
<INPUT TYPE="button" VALUE="Page down"
  ONMOUSEDOWN="javascript:document.MyApplet.scroll('pgdown');">
<INPUT TYPE="button" VALUE="Go home"
  ONMOUSEDOWN="javascript:document.MyApplet.scroll('home');">
<INPUT TYPE="button" VALUE="Go end"
  ONMOUSEDOWN="javascript:document.MyApplet.scroll('end');">  

...........................................................................

The other public function is scroll. Its purpose is to dynamically change
the source of the contents displayed by vText. It also takes a string as a
parameter, with the same meaning as the source parameter in the applet. He-
re are some examples of how it is used:

...........................................................................

<A HREF="javascript:document.MyApplet.reload('Hello world!');">Message</A>
<A HREF="javascript:document.MyApplet.reload('#anchor');">Anchor</A>
<A HREF="javascript:document.MyApplet.reload('@page2.txt');">Other page</A>
<A HREF="javascript:document.MyApplet.reload('@doc3.txt#anc5');">where?</A>

...........................................................................

If you are used to write your own javascript applets, surely you imagine
how useful can be these two functions to create dynamic behaviours. You can
even link two or more vText applets in different HTML frames.


8. RECOMMENDATIONS
------------------

Of course, vText has some performance tricks or limitations. Knowing them
can help you to use the applet in good conditions, and design your web
applications in order to get the best performance.

- COLOR MODES. As mentioned before, vText works best in 16 and 24 bit color
  modes which are, by far, the most frequently used by computer users.
  Other color resolutions should work reasonably well, but may produce some
  color errors when background images are used.

- LARGE CONTENTS. vText was designed to render small and medium sized con-
  tents. It is focused on getting a neat and clean display (justified text,
  smooth scroll, customization, etc.) rather than on mere capacity (after
  all, it does not intend to replace the Internet browser). So, very large
  and complex contents may require too much memory and/or processing time.
  It is better to divide large contents onto several "pages", and use vText
  reloading abilities.

- IMAGES. We all know the bandwidth problem when browsing Internet con-
  tents, so it is not a good idea to abuse of large images or big amounts
  of them. Actually this is a general consideration for any kind of web de-
  sign, so also applies to vText contents. There are also some other consi-
  derations about images in vText. Background images can slow down the ren-
  dering process. Don't use very small images as repeated patterns in the
  background. you can use animated GIFs in background and foreground ima-
  ges, but paragraph images are always shows as static.

- PRINTING AND COPYING. Text and images displayed by vText can not be di-
  rectly printed with the browser printing commands. This can be very use-
  ful when you want to prevent (or difficult) users from copying the text
  and images of your web pages. It also can be considered as a limitation
  if you want your pages to be printed or copyied by visitors. In this ca-
  se, an usual (and recommendable) technique is to have alternative pages
  that show the same contents but in a format which is very adequate for
  printing.

- VERIFICATIONS. In order to get a fast donwloadable web component, vText
  was designed to be as small as possible. It was not suitable to include
  exhaustive verifications for all posible situations, and they were deli-
  berately left out. For example, the program doesn't check if dimmensions,
  margins and sizes produce a coherent area, so it is your responsability
  to test the values you set are correct. This is not a problem because a
  glance at the visual results is usually the only test needed.


9. CONTACT INFORMATION
----------------------

In order to obtain the latest version of vText, ask any question about the
software or receive technical support (only for registered users), you can
follow these links:

Web: http://luis.pabon.com/vtext
E-mail: luis@pabon.com

Additional information about the license of use of this concrete distribu-
tion and how to purchase can be found in the LICENSE and REGISTER files.

vText 1.0 Java Applet
Copyright  2000 Luis M. Pabn
All rights reserved

