Freedom VR Documentation: adding hotspots

adding hotspots

This section assumes that you've mastered the art of making models without hotspots and now would like to graduate to adding hotspots.

How hotspots work

Freedom VR uses dynamic loading to implement hotspots. That is, the code for hotspots is stored in a separate java class from the rest of Freedom VR. This will make it possible to add new kinds of hotspots in the future without modifying the code -- it also means that new features can be added selectively so that users aren't going to be stuck donwloading a huge applet.

Freedom VR uses Javascript to embed hotspots. This is not 100% pure Java and thus doesn't work with MSIE 3.0 or HotJava, but it does work with Netscape 3.0 and up and it does with MSIE 4.0 and up. Using an existing language means that Freedom VR can be simpler and smaller. If you already know some javascript, then you'll have an easy time embedding hotspots. If you don't, you're not wasting your time if you learn a little since javascript is being widely used.

Example world

To learn how to use hotspots, take a look at this a sample world. If you do a View Source you'll find that the HTML and Javascript code is well-commented and explains what I'm doing. If you've got any questions about how the code works, write me and I'll clarify it.

The Hotspot Editor

Freedom VR 2 has a hidden feature which makes adding hotspots much easier. If you open the java console of your web browser, move the mouse over the applet and type 'x', Freedom VR will print out the frame you're viewing and the cursor location. You can use this to get the upper left corner... If you move the cursor and then hit 's' it will print the size of the rectangular box between the place you hit 'x' and the place you hit 's'. This way you can get the exact numbers to place your hotspots with very little work.

Details...

This is a preliminary explanation of how the hotspot interface works. After getting feedback from users I expect to refine it. Writing good documentation is a lot of work, so I need to know what people will find helpful.

You can learn about javascript here. First you might want to take a look at the code which inserts the applet in scene1.html... Things that are different from the previous examples are marked in red

<APPLET CODEBASE="../1d/" CODE="fvr2.class" HEIGHT=266 WIDTH=400 NAME="fred" ARCHIVE="../1d/fvr2Archive.jar">
  <PARAM NAME="nFrames" VALUE="12">
  <PARAM NAME="modelBase" VALUE="statue2/">
  <PARAM NAME="plugins" VALUE="RectangularHotspot">
</APPLET>

The purpose of the codebase tag is to tell the browser to look for the .class files in another directory so I don't need to install another copy of Freedom VR; I didn't use codebase in earlier examples because it's easy to make mistakes with it. The purpose of NAME="fred" is to give the applet a name to make it accessable to javascript. Finally, <PARAM NAME="plugins" VALUE="RectangularHotspot"> is a list of all the Hotspot classes that you'll be using. This ensures that Freedom VR will find and load the Hotspot classes.

The javascript contained in node 1 of the sample world is heavily commented -- every line is explained as well as the major foibles of Javascript. So your best bet is to view source it. The comments make the code look a lot longer than it is, so you might also want to take a look at node 2.

fvr2 methods accessable from Javascript

panRight

  public boolean panRight(int steps)

The following group of methods are used for moving the view. This may be of interest to Javascript programmers who would like to script Freedom VR, so they've been made public; the terms pan and tilt come from cinematography and are probably technically right only for the panorama case. Pan the view to the right.

Parameters:: steps - the number of frames to pan
Returns:: true if pan succeeded, false if it didn't.

panLeft

  public boolean panLeft(int steps)

Pan view to the left.

Parameters:: steps - the number of frames to pan
Returns:: true if pan succeeded, false if it didn't.

tiltDown

  public boolean tiltDown(int steps)

Tilt view down.

Parameters:: steps - the number of frames to tilt
Returns:: true if tilt succeeded, false if it didn't.

tiltUp

  public boolean tiltUp(int steps)

Tilt view up.

Parameters:: steps - the number of frames to tilt
Returns:: true if tilt succeeded, false if it didn't.

newHotspot

  public fvr2Hotspot newHotspot(String kind) throws ClassNotFoundException, InstantiationException, IllegalAccessException

This is a control binding for javascript: it's job is to make new Hotspot objects and interconnect them with the applet

Parameters:: name, - Hotspot name; frame_i, - Hotspot vertical frame #; frame_j, - Hotspot horizontal frame #; x - Hotspot x coordinate; y - Hotspot y coordinate; height - Hotspot height; width - Hotspot width

RectangularHotspot methods accessable from Javascript

Following is a list of methods of RectangularHotspot that can be called from javascript.

setFrame

  public void setFrame(int i,
                       int j)

Set the frame in which the Hotspot is in.

Parameters:: i - vertical frame index; j - vertical frame index

setCorner

  public void setCorner(int x,
                        int y)

Set the upper left corner of the Hotspot

Parameters:: x - vertical frame index; y - vertical frame index

setSize

  public void setSize(int width,
                      int height)

Set the size of the hotspot

Parameters:: width - width in pixels; height - height in pixels

setMouseUpURL

  public void setMouseUpURL(String s) throws MalformedURLException

Set the URL that we jump to when the mouse is released

Parameters:: s - string specifying a URL; can be either an absolute URL or a URL relative to the document base of the applet.

setMouseUpTarget

  public void setMouseUpTarget(String s)

Set the target window or frame for the mouseUpURL. If this isn't specified, the default is to pop the URL up in the same frame as the applet. This works the same as the TARGET option of the <A> tag in HTML.

Parameters:: s - string specifying a URL; can be either an absolute URL or a URL relative to the document base of the applet.

setMouseOverText

  public void setMouseOverText(String s)

Set the text which appears in the status bar when the mouse moves over the Hotspot.

Parameters:: s - text to appear in the status bar

setVisibleMouseOut

  public void setVisibleMouseOut(boolean b)

Is the Hotspot visible when the mouse is away from it?

setVisibleMouseOver

  public void setVisibleMouseOver(boolean b)

Is the Hotspot visible when the mouse is above it but not depressed?

setVisibleMouseDown

  public void setVisibleMouseDown(boolean b)

Is the Hotspot visible when the mouse is above it and depressed?

beInvisible

  public void beInvisible()

Make the hotspot completely invisible. This is equivalent to calling

hotspot.setVisibleMouseOut(false);
hotspot.setVisibleMouseOver(false);
hotspot.setVisibleMouseDown(false);

setMouseOutColor

  public void setMouseOutColor(String c) throws NumberFormatException

Colors are set with a hexadecimal value (#RRGGBB), the same format used for setting colors in HTML.

Parameters:: c - the color of the Hotspot's box when the mouse is away from it

setMouseOverColor

  public void setMouseOverColor(String c) throws NumberFormatException

Parameters:: c - the color of the Hotspot's box when the mouse is above it but not depressed

setMouseDownColor

  public void setMouseDownColor(String c) throws NumberFormatException

Parameters:: c - the color of the Hotspot's box when the mouse is above it and depressed