                                PopUp v2.0
----------------------------------------------------------------------------

        author:         Justin Sucharski
        date:           March 7, 1997
        email:          jsuchar@lynx.cs.usfca.edu

        classes:        PopUp.class
                        PopUpButton.class
                        messageFrame.class

        Any questions or comments should be directed to me at the above
        email address. I will be more than happy to answer any questions
        you have.

----------------------------------------------------------------------------
Features:
        
        - Supports up to 20 independent buttons
        - Three button states: up, down, on
        - Four sound states: up, down, on, off
        - Tiled background image
        - Optional popup message window
        - Nine text alignments
        - Optional button hilight and shadow
        - Relative or absolute addressing

----------------------------------------------------------------------------

  What is PopUp?
    PopUp is the most versatile button/menu applet that I could come up
    with. It allows up to twenty completely indepedant buttons on one menu.
    What sets PopUp apart from other applets of this type is the optional
    popup message frame which appears when the mouse is moved over a button
    and disappears when the mouse exits the button. The purpose of this
    is so that visitors to a web site will not have to guess what lies
    beyond the button. The scripting language gives this applet its power and
    versatility and is intuitive and easy to learn (I think so).

  How do I use PopUp?
    Use PopUp the same way you would any other applet. Below is a list of
    the parameters and a description of button definitions.

----------------------------------------------------------------------------
Applet parameters:

background              background image tile
bgcolor                 background color
hgap                    horizontal gap between buttons
vgap                    vertical gap between buttons

button#                 button parameters (# is the number of the button 0-20)

Button Parameters
----------------------------------------------------------------------------
General Syntax:
      For those of you who absolutely need it here's my feeble attempt at
      a BNF definition of the general syntax for defining buttons. Besides,
      I need the practice.
                <def> ::= <property> <def> | <property>
                <property> ::= <tag>=<keylist>;
                <tag> ::= button | images | sounds | ontext | uptext | downtext
                <keylist> ::= <key>,<heylist> | <key>
                <key> ::= <keyname>=<keyvalue>
                <keeyname> ::= width | height | title | message | fontfamily
                             | fontsize | fontstyle | bgcolor | fgcolor | on
                             | up | down | open | close | link | align | all
                             | shadow | show | target | dest[ination]
                <keyvalue> ::= <align> | <value> | <fontstyle>
                <align> ::= <alignkey>(<alignvalue>)
                <alignvalue> ::= <alignment>+<alignvalue> | <alignment>
                <alignment> ::= middle | center | right | left | top | bottom
                <alignkey> ::= up | on | down
                <fontstyle> ::= <font>+<fontstyle> | <font>
                <font> ::= plain | italic | bold
                <value> ::= <string> | <number>
                        ... I think you can handle it from here.

        NOTE: The "dest[ination]" means that all you need is the "dest".
              Anything after that is ignored within the keyname. 

TAGS:
      There are seven general tags listed here. These are followed by an
      equals sign and delimited by a semicolon. i,e, button=( <keys> );
      Note that the parentheses are optional and there is no order in which
      the options must be listed. None of the tags or keys are case sensitice.

  window   - defines the parameters of the popup window
    acceptable keys: show, fgcolor, bgcolor, height, width, title, message, fontFamily, fontSize
  button   - defines the general properties of the button includeing URL
    acceptable keys: height, width, dest, target, shadow
  images   - defines the button's images (three)
    acceptable keys: on, up, down, all, align
  sounds   - defines the sounds to be played (four)
    acceptable keys: open, close, down, link
  ontext   - defines text and colots when mouse is on button
    acceptable keys: alignw, fgcolor, bgcolor, message, fontFamily, fontSize, fontStyle
  uptext   - defines text and colots when button is up
    acceptable keys: alignw, fgcolor, bgcolor, message, fontFamily, fontSize, fontStyle
  downtext - defines text and colots when button is down
    acceptable keys: alignw, fgcolor, bgcolor, message, fontFamily, fontSize, fontStyle


KEYS:

  key                   description                     accepted values                                         examples
............................................................................................................................................................

  width         button/window width                     any integer > 0                                   width=150
  height        button/window height                    any integer > 0                                   height=200
  title         window title                            any string                                        title=Mine!
  message       button/window text                      any string                                        message=Back
  fontfamily    button/window font                      any font type                                     fontFamily=Ariel
  fontsize      button/window font size                 any integer > 0                                   fontSize=24
  fontstyle     button/window font style                plain, italic, bold                               fontStyle=plain , fontStyle=bold+italic
  bgcolor       button/window background color          6 digit hex RGB                                   bgcolor=88ff55
  fgcolor       button/window text color                6 digit hex RGB                                   fgcolor=00ff00
  on            image/alignmenr for mouse over          URL or top, bottom, right, left, center, middle   on=top , on=left+bottom , on=image.jpg
  up            image/alignmenr for button up           URL or top, bottom, right, left, center, middle   up=top , up=left+bottom , up=image.jpg
  down          image/alignmenr/sound for button down   URL or top, bottom, right, left, center, middle   down=top , down=left+bottom , down=image.jpg
  open          sound for mouse over                    URL of .au sound                                  http://www.host.com/sound.au
  close         sound for mouse exit                    URL of .au sound                                  http://www.host.com/sound.au
  link          sound for button up                     URL of .au sound                                  http://www.host.com/sound.au
  align         image/text alignment                    on, up, down                                      align=(on=left)  , align=(down=right+center)
  all           image for all three states              URL                                               all=http://www.who.net/image.jpg
  shadow        width of button shadow/highlight        any integer > 0                                   shadow=5
  show          show/hide popup message window          on, off                                           show=on  ,  show=off
  target        target frame                            any frame name (ie _self, _top, main)             target=main  ,  target=_top
  dest          button's destination URL                absolute or relative URL                          http://www.jars.com/  , /index.html  , index.html

----------------------------------------------------------------------------
EXAMPLES:

1) This creates a button with a message window, all three sounds, one image
     for all three states, and different text for each state. If you are
     curious what this button looks like exactly, it is the first button in
     my menu on my Java page.

  <param name="button0" value="window=(height=100, width=400, title=Main page, fgcolor=00ffbb, fontfamily=Ariel, fontsize=16, message=This will take you to the main page of this site which contains a Java resource list.);
                      images=(all=/~simcath/focus/pics/javamenu_ball.jpg);
                      sounds=(open=sound/java1.au, link=sound/java2.au, close=sound/java1.au);
                      button=(shadow=1, height=75, width=100, target=main, dest=javamain.html);
                      uptext=(bgcolor=000000, fontfamily=Ariel, fontsize=20, fgcolor=00ffff, fontstyle=plain, align=up(bottom), message=Main Page);
                      ontext=(bgcolor=000000, fontfamily=Ariel, fontsize=20, fgcolor=ffffff, fontstyle=bold, align=on(bottom), message=Main Page);
                      downtext=(bgcolor=000000, fontfamily=Ariel, fontsize=20, fgcolor=ff0000, fontstyle=italic, align=down(bottom), message=Main Page);">


2) This creates a button which uses one image for all states, has no text, no
     sounds, does not display a message window, and uses default colors with
     a highlight/shadow 5 pixels wide.

  <param name="button1" value="window=(show=off);
                      images=(all=/pics/image1.jpg);
                      button=(shadow=5, height=160, width=160, target=_top, dest=java.html);

----------------------------------------------------------------------------
HISTORY:

           August 4, 1996     - v1.0
           February 14, 1997  - v1.05
              Revised relative address function to work in any case (hopefully)
           February 17, 1997  - v2.0a
              Febuary 15, 1997
                  Added PopUpButton class
              February 17, 1997
                  Added background image tiling
                  Completed "window" parser
                  Completed "sounds" parser
                  Completed "button" parser
                  Added double buffering
                  Completed "image" parser
                  Completed "text" parsers
           March 4, 1997   - v2.0b
                  Fixed update related background color problem
                  Fixed drawShadow routine to look realistic
           March 13, 1997   - v2.0 release

----------------------------------------------------------------------------
KNOWN BUGS:

        No bugs as such, but there is one oddity of which to be aware.
        If a popup window appears over its button it will go spastic rapidly
        appearing and disappearing. I recommend that when using the window
        feature you place the menu on the bottom of right of your page as
        the windows appear in the upper left corner of the screen.

----------------------------------------------------------------------------
LEGAL CRAP:

      I hereby grant anyone with good intentions to use and modify this
      file for NON-COMMERCIAL use. This applet is by no means to be distributed
      via static medium. Any person modifying the source code may do so
      under the condition that they let me know what they have modified.

----------------------------------------------------------------------------

