Physlet Documentation

Physlet documentation is, unfortunately, still scattered in numerous locations. Java 1.0 Physlets and early Java 1.1 Physlets usually have their own documentation page. These pages are usually linked into each Physlet's archive. For many Physlets the best documentation may be the actual Physlet Problems themselves. Just view the html source and examine the script.

Fortunately, there is now a technical fix to keeping documentation up to date. The recently released the Java 2 platform has a much improved utility for generating documentation directly from the Physlet source code call javadoc. We have adopted this utility as the primary mechanism for the distribution of Physlet documentation and documentation will eventually be provided in this format.

See: Javadoc Output

JavaDoc

Javadoc is something that only a geek could love.[1] The program extracts every detail about a Java class from the source code and outputs these details using html. This section presents an anatomy of this output for the non-programmer.

Javadoc produces an html page for each Java object that is processed. In our case, these Java objects are Physlets. The program organizes these multiple output files using html frames. The left frame displays a table of contents, TOC, listing the Physlet or package for which documentation has been generated. Each TOC entry is hyper-linked to the appropriate file and clicking on this link loads the page into the right frame.

Text Box: animator4 
Class Animator
java.lang.Object
  |
  +--java.awt.Component
        |
        +--java.awt.Container
              |
              +--java.awt.Panel
                    |
                    +--java.applet.Applet
                          |
                          +--edu.davidson.tools.SApplet
                                |
                                +--animator4.Animator

 

 

 

 

 

 

 

 

 

 

 

Figure 1: Class hierarchy for generated by javadoc.


Class Hierarchy

Documentation pages begin by showing the class hierarchy of an object.

 

 

 

 

 

 

 

 

 

 

 

Figure 1 shows that the Animator Physlet is a subclass of SApplet which itself is a subclass of Applet. This parent child relationship can be followed to the root of all Java objects called, in typical engineering fashion, Object. Since a child can perform any of the methods defined in a parent, Animator can perform any method defined in any of its six superclasses. Since the Physics that we wish to script was added to the Applet class by the SApplet and the Animator subclasses, we usually only need to concern ourselves with the methods listed in these last two levels.

Method Summary and Detail

 

Method Summary

 int

addObject(java.lang.String name, java.lang.String parList)
          Create an object and add it to the Physlet.

 void

forward()
          Start the animation.

Below the class hierarchy is a table summarizing every available public, i.e., scriptable, method. The first column indicates the data type that is returned when the method is executed. For example, the addObject method in the above table returns an integer while the forward method does not return any value. Not returning a value is indicated by the keyword void. The second column is more interesting since it lists the object name and its signature. The signature consists of a comma-delimited list of data types and variable names. Following the signature is a short description of the method.

 

Text Box: addObject
public int addObject(java.lang.String name,
                     java.lang.String parList)
Create an object and add it to the Physlet. The first argument is the name of the object to be added and the second is a comma-delimited list of parameters. For example, a circle can be added a follows: 
addObject ("circle", "x = 0, y = -1.0, r = 10"); 
See the supplemental documentation for a list of object names and parameters. 
Parameters: 
name - the type of object to be created. 
parList - a list of parameters to be set 
Returns:  integer id that identifies the object.

 

 

 

 

 

 

 

 

 

 

Figure 2: Method detail for the addObject method in Animator.

Names in the method summary are actually hyperlinks to more detailed descriptions further on down the documentation page as shown in

 

 

 

 

 

 

 

 

 

 

 

Figure 2. In addition to a more extensive description, detail summaries usually provide descriptions of parameters and return types.

Javadoc generates numerous other tables including lists of methods that are defined in the various superclasses. This fire hose of information is more intimidating than useful to JavaScript programmers. The exception is the SApplet superclass since it contains the animation clock and the data connections. But you should click on the hyperlink to SApplet rather than trying to decipher SApplet by studying the cryptic listing in the subclass documentation.

Inherited Methods

A typical Physlet will have dozens of public methods designed to control its behavior and appearance using JavaScript. Many of these methods are unique to each applet but certain methods are of sufficient utility that they reoccur. Many if these reoccurring methods have been moved to the common Physlet superclass, SApplet. SApplet is, therefore, the logical place to start documenting Physlets.

Clock Methods

SApplet contains an animation clock that is available even if the applet does not appear to use animation. The behavior of this clock can be scripted through the following methods. See the DataGraph tutorial for an example as to how this clock can be used to generate data for onscreen display.

 

Method

Description

cyclingClock( )

This method is called whenever the clock reaches its maximum value in cycle mode. Override this method and reset the applet into its initial state.

forward( )

Start the clock with a positive time step.

pause()

Pause the clock at the current time.

reset()

Reset the applet to its initial state. The clock should be set to zero or to the minimum time if the click is in oneShot or cycle mode.

Override this method in order to set other conditions such as initial position or velocity.

See also: setDefault under miscellaneous methods.

reverse()

Start the clock with a negative time step, dt.

setDt(dt)

double dt
animation time step

Set the time step for each clock tick. Usually not scripted since the time step is set with the <PARAM>tag when the applet is embedded. The default behavior calls clock.setDt.

Example: setDt(0.1)

Note: Animation time corresponds to actual time if fps*Dt=1.

setFPS(fps)

double fps
frames per second

The number of clock ticks per second. Usually not scripted since fps is set with the <PARAM>tag when the applet is embedded. Each tick will often result in a new animation frame, hence the use of FPS (Frames Per Second) in the name.

The default behavior calls clock.setFPS.

Example: setFPS(10)

Note: Animation time corresponds to actual time if fps*Dt=1.

setTimeContinuous()

Animation time will increase without limit when the clock is running.

setTimeCycle(double)

double max
the maximum time

Animation time will cycle between 0 and a maximum value.

Example: setTimeCycle (10); // time will cycle at 10

setTimeOneShot(max,msg)

double max
the maximum time

String msg
a display message for the user.

Animation will run from t=0 to a maximum time. When the clock reaches its maximum time the clock will stop and the stoppingClock(String) method is called.

Example: setTimeOneShot (10, "End of animation.");

The message is stored in the oneShotMsg variable:
protected String oneShotMsg

stepTimeBack()

Step the clock back by one time step, dt. If the clock is running the pause method is called.

stepTimeForward()

Step the clock forward by one time step, dt. If the clock is running the pause method is called.

stoppingClock()

This method is called whenever the clock reaches its maximum time in one-shot mode. The applet author should override this method to display the oneShotMsg on the screen.

 

Data Connections

Inter-applet communication could not occur without the common SApplet superclass. The connection that is established is actually an object and like any object, this connection has properties that can be set. Setting a data connections properties requires that the identifier returned by the makeDataConnection method be passed as the object's id.

 

Method

Description

clearAllData()

Send the clear series command to all data listeners. This usually deletes all the data in the data listener.

clearData(id)

int id
the object identifier

Clears a single data connection with the given object identifier, id.

deleteDataConnection(id)

int id
the object identifier

Break the data connection to the data listener. The data listener is not cleared.

deleteDataConnections()

int id
the object identifier

Break the data connections to the all data listeners. Data listeners are not cleared.

makeDataConnection(sid, lid,
series, fx, fy)

int sid
data source id

int lid
data listener id

int series
data listener series

String fx

function to be evaluated for x

String fy

fuction to be evaluated for y

 

return int

object identifier

 

Create a data connection between a data source and a data listener. The two string parameters, fx and fy, are mathematical functions of the data source variables. These functions are evaluated by the data connection to produce either a data point (fx, fy) or an entire array of data (fx[], fy[]) that is then passed on to the data listener.

 

Returns the object identifier for the connection.

setConnectionBlock(id, block)

int id
the object identifier

boolean block
block if true.

Block the connection from accepting data. Unblocking can occur at any time.

setConnectionSmoothing(id,num)

int id
the object identifier

int num
number of points to average

Smooth data as it passes through the connection. If the data source sends an array of points, nearest neighbors will be averged.

setConnectionStride(id,num)

int id
the object identifier

Set the data connection to skip every num-1 points.

updateDataConnection(id)

int id
the object identifier

Send data from the data source.

updateDataConnections()

Send data from all data sources.

 

Miscellaneous Methods

 

Method

Description

setAutoRefresh(ar)

boolean ar
true if applet should redraw itself after changes are made.

Determines if the applet will recalculate and repaint every time a parameter changes. Set this parameter to false at the beginning of a long script in order to eliminate screen flash and reduce unnecessary processing. AutoRefresh should be set to true at the end of a script.

This method should be overridden in each applet. The default method merely sets the autoRefresh variable.

protected boolean autoRefresh=true;

setDefault()

Reset the applet to a predetermined initial state. The default method sets the animation time to zero and removes all existing data connections. Programmers should override this method to set other default conditions.

See also reset() in the table of clock methods.

 

Naming Conventions

Common Methods

Inherited methods that were listed in the last chapter are guaranteed to be available in every Physlet that inherits from SApplet. Common methods, on the other hand, are applet specific. These methods may, or may not, be implemented. Use the following table as a guide, but consult the online documentation for an applet to determine if the method is available.

 

Method

Description

addObject(name, list)

String name
the object to be added

String list
a list of settable properties

return int
object identifier

Create an object and add it to the simulation. This method should be implemented in any applet that is designed to instantiate data sources using JavaScript. Instantiated objects are often, but not always, drawn on the screen. Returns an object identifier, usually the hashCode().

Example: addObject("circle","x=2,y=3,r=8")

Note: Methods in the edu.davidson.tools.SUtil class, such as parameterExist and getParam, are can be used to parse the properties list.

getVX(id)

int id
the object identifier

return double
x

Read the x coordinate of an object.

getVY(id)

int id
the object identifier

return double
x

Read the x coordinate of an object.

getX(id)

int id
the object identifier

return double
x

Read the x coordinate of an object.

getY(id)

int id
the object identifier

return double
y

Read the y coordinate of an object.

set(id, name, list)

int id
the object identifier

String name
the object to be added

String list
a list of settable properties

return int
object identifier

Set an object's properties. Similar to the addObject method except that the object must already exist. An id of 0 can be used to signal the default object.

This is a new method that we have not yet widely implemented. We believe, however, that this method would be easier to use and less error prone for setting complex data structures. For example

set(0,"scale","xmax=20, autoScaleY");

can now used to set the scale in DataGraph Physlet. The x axis maximum value is given a new value and the y axis is set to autoscale. All other scale parameters are left unchanged.

Expect to see this method adopted in new applets.

setDragable(id, drag)

int id
the object identifier

boolean drag
true if object is dragable

Make the object with the specified id dragable. Returns true if the object exists.

Example: setDragable(id,true)

setRGB(id, r, g, b)

int id
the object identifier

int r red
int g green
int b blue

return boolean
objects exists

Set the color of the object. Returns true if the object exists.

Example: setRGB(id,255,0,0); // sets the object's color to red

setX(id, x)

int id
the object identifier

double x
the x value

Set the x coordinate of an object.

setXY(id, x,y)

int id
the object identifier

double x
the x value

double y
the x value

Set the x and y coordinates of an object simultaneously.

setY(id, y)

int id
the object identifier

double y
the x value

Set the y coordinate of an object.

setVisibility(id,vis)

int id
the object identifier

boolean vis
true if the object is visible on the screen

Set the visibility of any onscreen object.

Special case: Time display is affected if the id is that of the clock.

Example:

id=getClockID();
setVisibility(id, false); // disable the time display in the UI

 

AddObject Method

Almost all Physlets support one or more add methods designed to create an object and add it to the applet. These objects usually, but not always, have an on-screen representation. For example, both Animator and EField support addCircle methods that are invoked using the following JavaScript statements

 

document.animator.addCircle(int,String,String)

and

 

document.efield.addCircle(double, double, int),

respectively.

Notice that the signatures, that is, the parameters, of these two methods are different. Animator version 1 was designed to move simple geometric shapes along predefined trajectories that were passed to the object's constructor. EField version 1, on the other hand, was designed plot electric fields for fixed charges. Its add method required fixed positions. Hence, animator was passed two functions of time and EField was passed two numbers. Both applets were designed to run on 90 MHz computers with relatively slow Java virtual machines. Since each applet only had half a dozen methods, it was not difficult to remember the correct signature. However, advances in computer hardware and software have made it possible to add a great deal of functionality to these two applets. Animator now supports particle interactions and EField supports dynamic test charges. Although their capabilities have converged, their method names have not.

In order to bring some order to this method madness, version 4 of Animator and EField, along with newly written Physlets, have adopted a uniform convention for adding objects. Both applets now support an addObject method with the following signature

 

document.physletname.addObject(String, String)

The first argument is the name of the object to be added and the second is a comma-delimited list of parameters. A circle can now be added to either applet using the following statement

 

document.physletname.addObject("circle",

"x=0,y=-1.0,r=10");

Furthermore, the new method is more forgiving since not all parameters need be specified. Default values are overridden only if the parameter appears in the list. Incorrect and unsupported parameters do not affect the applet and are ignored.[2]

The table below lists the name and the associated parameters for version 4 of the EField and Animator Physlets. An X in the A or E column indicates that the named object can be added. Consult the online documentation for information about other Physlets. DataGraph, for example supports the addObject method for geometric shapes such as circles, boxes, and shells. OpticsBench, on the other hand, supports the addObject method for lenses, mirrors, and light sources.

 

Name

Attributes

A

E

arrow

Arrows are often animation slaves of other objects. They can represent almost any vector since the h and v components can be functions of the variables.

x- double x position of the base in world units

y- double y position of the base in world units.

h- string horizontal component as a function of t, x, y, vx, vy, ax, and ay.

v- string vertical componenst as a function of t, x, y, vx, vy, ax, and ay.

x

x

box

A box is a hollow rectangle.

x- double The x position of the center in world units

y- double The y position of the center in world units.

h- int The height in pixels.

w- int The width in pixels.

x

x

circle

x- double The x position of the center in world units

y- double The y position of the center in world units.

r- int The radius in pixels.

x

x

caption

A caption is text that is centered near the top of the screen.

text- string The text of the caption

calc- string A function of t to be evaluated at every time step. The value of the function is displayed to the right of the text.

x

x

charge

x- double The x position of the center in world units

y- double The y position of the center in world units.

q- double The object's charge.

r- int The radius in pixels.

 

x

connectorline
A straight line connection two objects.

id1- int The first object identifier.

id2- int The second object identifier.

 

See also addConnectorSpring(int,int) in the online documentation. This method is easier to use if the ids are stored as integers.

x

x

connectorspring
A spring connection two objects.

id1- int The first object identifier.

id2- int The second object identifier.

 

See also addConnectorSpring(int,int) in the online documentation. This method is easier to use if the ids are stored as integers.

x

x

cursor

A circle with cross hairs.

x- double The x position of the center in world units

y- double The y position of the center in world units.

r- int The radius in pixels.

x

x

exshell

Extended shell is similar to shell except that the radius can be a function of time. Useful for shock waves and space-time diagrams.

x- double The x position of the center in world units

y- double The y position of the center in world units.

r- string The radius in world units as a function of time

s- int The thickness of the shell in pixels.

x

 

image

Add an animated gif image. The coordinates are the coordinates of the upper left hand corner.

x- double The x position of the left side in world units

y- double The y position of the top in world units.

file- string The name of the gif file. The image should be in located in the same directory as the jar file for the applet.

x

x

line

 

 

 

 

 

x- double The x position of the base in world units

y- double The y position of the base in world units.

h- string The horizontal component as a function of t, x, y, vx, vy, ax, and ay.

v- string The vertical component as a function of t, x, y, vx, vy, ax, and ay.

x

x

polyshape
polyshape draws an arbitrary shape by connect-the-dots. The shape is specified by passing the pixel positions of the dots starting at x and y.

x- double The x position of the center in world units

y- double The y position of the center in world units.

n- int The number of vertices in the polygon.

hStr- string A comma separated list of the x postions of the vertices in pixel units.

vStr- string A comma separated list of the y postions of the vertices in pixel units.

x

 

rectangle

x- double The x position of the center in world units

y- double The y position of the center in world units.

h- int The height in pixels.

w- int The width in pixels.

x

x

relshape
relshape draws an arbitrary shape by connect-the-dots. The shape is specified by passing the relative pixel positions of the dots starting at x and y.

x- double The x position of the center in world units

y- double The y position of the center in world units.

n- int The number of vertices in the polygon.

hStr- string A comma separated list of the x postions of the relative vertices in pixel units.

vStr- string A comma separated list of the y postions of the relative vertices in pixel units.

x

 

shell
a circle with a hollow center

x- double The x position of the center in world units

y- double The y position of the center in world units.

r- int The radius in pixels.

x

x

testcharge
a charge that is free to move under the action of fixed charges and an external potential.

x- double The x position of the center in world units

y- double The y position of the center in world units.

vx- double The x velocity in world units

vy- double The y velocity in world units.

q- double The object's charge.

r- int The radius in pixels.

 

x

text
a fixed text string followed by a calculation.

x- double The x position of the left side of the text in world units

y- double The y position of the top of the text in world units.

text- string The static text.

calc- string A function of t, x, y, vx, vy, ax, and ay that is evaluated at every time step. The value of the function is displayed to the right of the static text.

x

x

 



[1] Geek is a technical term used by programmers to refer to members of their community who are held in high regard. It may be pejorative when non-programmers to refer to programmers since geeks were originally carnival performer who publicly ate or swallowed live animals.

[2] Users of old scripts should note that although the original add methods are still included in version 4 for backward compatibility, they have been depreciated. In addition, there have been structural changes in the tools package. The original STools.jar and SGraphics.jar have been combined into a single archive called STools4.jar. Consequently, the archive attribute for the Animator Physlet has changed from

archive="Animator3_.jar,SGraphics.jar,STools,jar"
to

archive="Animator4_.jar,STools4.jar."