0.0 Contents
1.0 Legal Notices and Restrictions
Entire contents Copyright © 1997–2001 by Key Curriculum Press Inc.
Right is granted to freely use DR1, DR2, DR3, and DR4 of the
JavaSketchpad (JSP) applet in your own Web pages, provided you do
so for non-commercial use only. (Other licensing terms are available;
contact Key Curriculum Press
for details.)
2.0 Purpose
This document describes the mechanism by which Web pages interact with
the JavaSketchpad applet, and describes the grammar used by the
applet to specify arbitrary geometric constructions.
This document describes the DR4 release of the JavaSketchpad
applet. See the Document
Revision History for a brief summary of what's new in DR4.
3.0 Applet Invocation
JavaSketchpad is implemented by a set of Java™ .class files that
live inside a directory on your Web server named JSP. Individual Web pages
link to this directory, so that viewers' browsers can find download the
necessary Java to make viewing your Web page possible.
An individual Web page can contain one or more invocations of the
applet, which will correspond to separate "dynamic geometry" illustrations
on the Web page.
Here is an example HTML invocation of the JavaSketchpad applet
that creates a dynamic triangle. Individual portions of this invocation
are described below.
- <APPLET CODE="GSP.class"
CODEBASE="jsp" ARCHIVE="jsp4.JAR" WIDTH=200 HEIGHT=150
ALIGN=left>
- <PARAM NAME=Frame VALUE=1>
- <PARAM NAME=Construction
VALUE="
- { Three vertices }
- {object#1} Point (144,130);
- {obj#2} Point (24,130);
- {#3} Point (84,20);
- { And triangle connecting them }
- Segment (3,1) [thick];
- Segment (1,2) [thick];
- Segment (2,3) [thick];
- ">
- Sorry, your Web browser is not Java
compatible. This prototype will not be of much interest to you.
- </APPLET>
3.1 <APPLET> </APPLET> Tags
These are standard HTML tags for invoking a Java applet. Any tags
contained between this pair are considered applet-specific. Any normal
HTML inside this pair is made available to browsers that do not support
Java. You can change the text ("Sorry, your Web browser is not Java
compatible...") to something more appropriate, such as a .GIF of the
dynamic illustration. (Of course, this .GIF won't be dynamic, because
dynamic geometry requires JavaSketchpad.)
The <APPLET> tag has several sub-parameters that are discussed in
this section.
3.11 CODE parameter
CODE indicates the name of the Java .class file to first load, and
should not be changed from "GSP.class".
3.12 CODEBASE parameter
CODEBASE indicates the path name of the directory in which the applet
exists on the Web server, relative to the URL of the Web page containing
the <APPLET> tag. You should not change the name of this directory
from "JSP", but if your Web page is stored in a directory on the server
other than the directory that contains the JSP
applet directory, you will need to provide a relative path-name
that specifies how to find the JSP directory from the directory in which
the Web page resides.
3.13 ARCHIVE
parameter
ARCHIVE indicates the filename of a .JAR archive containing all of the
.class files stored in the JSP directory. Recent Web browsers have the
ability to extract applets from a single archive file, rather than
download them as a collection of separate .class files. This results in
substantially less network delay when downloading an applet from a distant
Web server. However, not all Web browsers understand the archive format,
and so your JSP directory should contain both a .JAR archive
and individual .class files. (All of these files come with the
default JSP distribution directory.)
ARCHIVE should always be set to "jsp4.JAR" for this release of
JavaSketchpad.
3.14 WIDTH, HEIGHT, and ALIGN parameters
These are standard HTML parameters indicating the size (in pixels) and
alignment (relative to surrounding HTML text) of the applet's display on
your Web page.
3.15 HSPACE and VSPACE parameters
These are standard HTML parameters indicating the space (in pixels) by
which you'd like to separate the applet window from surrounding text
horizontally (HSPACE) and vertically (VSPACE). Note that the value
specified by one of these parameters is added to both sides of the applet:
HSPACE=5 creates five pixels of "margin" between text on the left and text
on the right of the applet window.
Leaving these unspecified is the same as specifying HSPACE=0 and
VSPACE=0.
3.2 Java Parameters
Inside the <APPLET></APPLET> pair, you specify inputs to
the JavaSketchpad applet by using the <PARAM>tag. In general,
this tag has the form
<PARAM NAME={variableName}
VALUE={variableValue}>
where {variableName} and {variableValue} change depending
on context. DR1 of JavaSketchpad supports several different
parameters.
3.2.1 Offscreen parameter
The Offscreen parameter may be passed to invocations of the applet with
values 0 or 1. 1 indicates that JavaSketchpad should use offscreen,
or "double-buffered" graphics, when animating geometric constructions.
This form of graphics increases the apparent (visual) smoothness of
animation, but decreases the overall speed of animation. While, in
general, you'll want offscreen graphics, be aware that some browsers
already double-buffer all Java applets. The result of a double-buffered
applet on a double-buffered browser is quadruple buffering, which is no
smoother than double-buffering but is twice again as slow. If you're
designing Web pages for use primarily with a specific browser, and you
know that the browser already offers double-buffering, set this value to
0. Otherwise, set it to 1, or leave it unspecified, as 1 is the default
value for this parameter.
3.2.2 Frame parameter
The Frame parameter may be passed to invocations of the applet with
values 0 or 1. 1 indicates that the sketch should appear in a frame, 0
indicates no frame should be used. The frame is a 1-pixel border with a
1-pixel drop shadow on the bottom right. Note that this frame is
considered part of the WIDTH and HEIGHT of the applet (as mentioned
above), rather than a separate border that extends the specified WIDTH and
HEIGHT by one pixel.
3.2.3 Construction parameter
The Construction parameter specifies the complete dynamic geometry
construction that JavaSketchpad will present to your viewer.
Constructions are described in section
4.
3.2.4 Background color parameters
By default, Java sketches appear against a neutral gray background. You
can specify any other color for a background by using the BackRed,
BackGreen, and BackBlue parameters. Each of these parameters takes a value
between 0 and 255; together, they specify a single composite color in a
16-bit color space. (In the red-green-blue model of color space, [0, 0,0]
specifies black, [255, 255, 255] white, and [n, n, n] a shade of gray.)
The default value for each of these parameters is 200.
Example:
<PARAM NAME=BackRed VALUE=255>
<PARAM NAME=BackGreen VALUE=0>
<PARAM NAME=BackBlue VALUE=0>
Sets the background color of an applet to bright (full) red.
3.2.5 Font parameters
While the current release of JavaSketchpad does not support
different fonts for different objects (like measurements) or object
labels, it does provide three separate font appearances for (all)
measurements, labels, and action buttons. You can change the global
appearance of these types of objects using parameters.
3.2.5.1 Label Font parameters
LabelFont specifies the font used to display labels. Its value can be
any valid Java font: "TimesRoman", "Helvetica", "Courier", etc. (Note that
Java fonts are not the same as Macintosh® or Microsoft® Windows® fonts!)
LabelSize can be any value between 6 and 100, and specifies the font size
in points. LabelBold can be 0 or 1, and indicates whether labels should
appear in bold (1) or regular-weight (0) type. LabelItalic can be 0 1, and
indicates whether labels should appear in italic (1) or regular-faced
type.
The defaults for these parameters specify 12-point Helvetica
boldface.
3.2.5.2 Action Button Font parameters
ActionFont, ActionSize, ActionBold, and ActionItalic provide similar
control over the appearance of action buttons. They default to 14-point
TimesRoman plainface.
3.2.5.3 Measurement Font parameters
MeasureFont, MeasureSize, MeasureBold, and MeasureItalic provide
similar control over the appearance of measurements. They default to
10-point Helvetica plainface.
3.2.6 Measurement Unit parameters
While the current release of JavaSketchpad does not support
different units for individual measurement objects, it supports two
parameters that globally affect the display of units.
3.2.6.1 Angle Unit parameter
The MeasureInDegrees parameter (values 0 or 1) indicates whether angle
measurements should be reported in radians (0) or degrees (1). The default
setting is radians.
3.2.6.2 DirectedAngles parameter
The DirectedAngles parameter (values 0 or 1) indiates whether angle
measurements are directed (between -pi...pi radians, or -180...+180
degrees) or undirected (between 0...pi radians or 0...180 degrees). By
default, JavaSketchpad reports directed angle measurements; i.e.,
the default value of this parameter is 1. Note that directed angles are
positive in the counter-clockwise direction and negative if they "open" in
a clockwise direction.
4.0 The Construction Grammar
Overview
A Construction consists of a set of one or more object definitions.
Each object definition is of the following form:
{objectName} {objectArguments} {optionalFormats}
;
Thus in the construction illustrated above,
Segment (3,1) [thick];
corresponds to an {objectName} of "Segment", an
{objectArguments} list of "(3, 1)", and {optionalFormats} of
"[thick]".
4.1 Comments
Any text contained inside curly braces { and } is ignored by
JavaSketchpad. If you are writing Constructions by hand (rather
than using desktop Sketchpad to generate them automatically), you
can use curly braces to provide comments to yourself or other readers
describing individual portions of the Construction.
4.2 {objectNames}
Individual {objectNames} identify both the type of geometric
object (point, line, etc.) and its geometric behavior (midpoint,
point-on-object, etc.). The complete list of {objectNames} known to
Sketchpad is described below (section
5).
4.3 {objectArguments}
{objectArguments} are a parenthesized list of comma-separated
values that characterize the exact geometric definition of a particular
{objectName}. The interpretation of any {objectArgument} varies
depending on the {objectName} and are described below (section
5). However, individual arguments fall into the following
categories:
4.3.1 {numericConstants}
{numericConstants} are simply numbers. They may have preliminary
negation symbols and zero or one decimal points.
4.3.2 {objectReferences}
{objectReferences} refer to other objects previously defined in
the Construction. In DR1 JavaSketchpad, {objectReferences}
are numbers that identify a previously-constructed object by index into
the entire list of object definitions. Thus the statement
Segment (3, 1) [thick];
contains two {objectReferences}: 3 and 1. These refer to the
third and the first object described in the construction. (In the example
complete construction above, these are in turn "Point (84, 20);"
and "Point (144, 130);".
It is illegal for any object definition (say, of object X) to contain
an {objectReference} that refers to some other object Y that is
defined after X in the Construction.
4.3.3 {strings}
{Strings} are arbitrary sequences of characters inside single
quotation marks ('). Example strings are:
'Sketchpad!'
'njackiw.gif'
Note that the quotes are part of the {string} definition itself,
rather than simply punctuation used in this document. {Strings}
cannot contain single quotation marks themselves, because quotation marks
are used to delimit the {string}'s beginning and end. Thus the
following is an illegal string:
'He said: 'This will never work.''
However, you can embed single quotation marks in a string if you
duplicate them in the string's declaration. The following source text,
'He said: ''But this will!'''
is legal and produces the following string:
He said: 'But this will!'
You cannot use double-quotation marks inside strings (") whatsoever, as
HTML defines the double-quotation mark (") as terminating the Construction
parameter.
4.4 {optionalFormats}
{optionalFormats} provide information about the style and color
of an object. They are optional in the sense that if you provide no
{optionalFormats}, or if you provide only partial formats,
JavaSketchpad will use default values for objects' unspecified
styles and colors.
{optionalFormats}, if present, are comma-separated values inside
square brackets. An example {optionalFormat} is
[thick, red]
The following formats are currently supported, though not all formats
make sense for all {objectNames}.
4.4.1 Named Color formats
You may assign any color to any object. Named colors are convenient for
specifying the colors familiar to default Sketchpad: "red", "blue",
"magenta", "cyan", "green", "black", "white", or "yellow". If you don't
specify a color explicitly, JavaSketchpad assigns a default color
that varies with the type of object being constructed.
Named colors are equivalent to the following "full-color" formats (see
section
4.4.2).
| red |
color(255, 0, 0) |
green |
color(0, 255, 0) |
| blue |
color(0, 0, 255) |
black |
color(0, 0, 0) |
| magenta |
color(255, 0, 255) |
white |
color(255, 255, 255) |
| cyan |
color(0, 255, 255) |
yellow |
color(255, 255, 0) |
4.4.2 Full-Color formats
You may also assign an arbitrary color to any object using the color
format specifier, which allows selection from a 16-bit color palette. The
color specifier should be followed by a parenthesized list of three
comma-separated numeric entries, each ranging from 0-255 in value. The
first entry specifies the red component of the desired color, the second,
the green component, and the third, blue.
Example:
point (35, 50) [color(128, 0, 128)];
Creates a point at (35, 50) on the coordinate plane, colored dusty
purple.
4.4.3 Line Weight formats
You may assign a thick line style to any ray, line, segment, or circle
by specifying the "thick" format attribute. Absence of "thick" format
implies thin format (i.e., the default line weight for objects is thin).
The current release of JavaSketchpad does not support dashed line
weights.
4.4.4 Visibility formats
You may hide a geometric object by specifying a "hidden" format
attribute. Absence of "hidden" implies that an object is showing, which is
the default visibility for JavaSketchpad objects.
4.4.5 Text Suffix
formats
Text suffix formats are only applicable to measurement objects. (It's
an error to specify a suffix format to any object other than a
measurement.) The suffix of a measurement is text that follows the numeric
value of the measurement in its display. For example, in
The wall is 3.2 meters from the fireplace.
the text " meters from the fireplace." is the suffix. (Note the
preliminary space in the suffix; sufficies began after the last numeric
character of the measurement value.)
You can set a measurement's suffix using the "suffix" attribute,
followed by a parenthesized string containing the actual suffix text.
Example:
Length(1, 100, 100, 'The wall is ') [suffix(' meters from the
fireplace'), blue];
Constructs the example measurement shown above, and positions it at
(100, 100) on the coordinate plane.
4.4.6 Auto-start
formats
Auto-start formats are only applicable to action button objects. (It's
an error to specify an auto format to any object other than a button.) The
presence of the "auto" format tells JavaSketchpad that the
formatted button should be automatically pressed when the applet starts.
This allows you to create applets that automatically present an animation
to the user, rather than require manual interaction.
In the current release of JavaSketchpad, at most 5 buttons can
specify the auto format. Usually, you'll only want at most one (an
animation or movement). It's not generally a good idea to apply "auto"
formats to Show or Hide action buttons, as the user may not be looking at
the applet when these single actions take place (immediately after the
applet is displayed).
4.4.7 Label Formats
In this release of JavaSketchpad, label formats are only
applicable to point objects. (It's an error to specify a label to any
object other than a point.) The "label" specifier should be followed by a
parenthesized string indicating the label, if any, with which you want the
point to appear. Points without label format specifiers appear
unlabeled.
Example:
Point(50, 100) [label('Center'), white]
Creates a white point labeled "Center" at (50, 100) on the coordinate
plane.
By default, labels always appear in the global label
font.
4.4.8 Traced formats
Specify that an object is to leave a traced "after-image" of itself
while it moves by adding the "traced" format attribute. By default, an
object is not traced.
4.4.9
Layer formats
Specifies that an object is drawn "on top" of other objects in its
layer. By default, JSP sorts objects into various visual layers: points
always appear "on top" of segments or polygons, for instance. Within a
layer, objects are unsorted. By adding a Layer format to the object, you
specify how it layers on top of, or beneath, other objects in its layer.
The Layer format attribute is followed by a parenthesized integer in the
range 1..1000, where high valued objects appear on top of objects with
lower values. Values do not have to be consecutive.
Example:
Polygon(1,2,3)[layer(10), white];
Polygon(4,5,6)[layer(20),
blue];
Circle interior(7)[layer(5)];
In this example, the two polygons will always appear on top of the
circle interior, and the blue polygon will appear on top of the white
one.
4.4.10 Image formats
Specifies the URL of an image (.gif or .jpg file) to display as an action
button instead of the text-based title that action buttons display by
default. The Image format attribute is followed by a parenthesized string
giving the URL of the image relative to the codebase of the applet.
Example:
ShowButton(10,10,'unused')(1, 2,
3)[image('map.gif')];
This creates a button that shows (presumably hidden) objects #1, #2,
and #3. The button appears with its upper-left corner at (10, 10) within
the applet window. The button's title is "unused," but this does not
appear in the applet window, since the button displays an image rather
than a text title (due to the presence of the image format attribute). The
image displayed by the button is given by the file map.gif, which is
located at the codebase of the JSP applet.
4.4.11 Text Style Formats
Text style formats allow you to override the default style of any text
object (caption or measurement). Supported formats include:
- bold
- italic
- plain
- size(number)
- font(string)
- justifyLeft
- justifyRight
- justifyCenter
Example:
FixedText(10, 10, 'Pythagorean Theorem')[size(24), bold,
font('Courier')];
This example creates a caption located at (10, 10) displaying the words
"Pythagorean Theorem" in a 24-point bold Courier font.
5.0 Legal Object Constructions
This section lists all {objectNames} currently known to the
current release of JavaSketchpad, as well as the interpretation of
their {objectArguments}.
This section is broken down into several sub-sections, corresponding to
the type of object created by the construction. The current release of
JavaSketchpad understands point, ray, line, segment, circle,
interior, image, measurement, and button objects.
5.1 Constructions That Create Points
5.1.1 Point (num1, num2);
Defines a point with no parents at an arbitrary location in the plane.
num1 and num2 define the (x, y) position of that point
relative to the pixel coordinate system of the applet's window.
JavaSketchpad allows users to drag Points to new locations in
the applet's window.
5.1.2 FixedPoint (num1, num2);
Defines a point with no parents at an arbitrary location in the plane.
num1 and num1 define the (x, y) position of that point
relative to the coordinate system of the applet's window.
Unlike Points, JavaSketchpad prohibits users from dragging
FixedPoints. (Note that FixedPoints are never present in Constructions
created by desktop Sketchpad, in that all points in desktop
Sketchpad can be dragged. However, for your JavaSketches, you may
find it convenient to allow only some points to be dragged while keeping
others fixed.)
5.1.3 Midpoint (objRef);
Defines the midpoint of a segment referenced by objRef.
5.1.4 Point on object (objRef,
number);
This defines a point whose domain is limited to a segment, ray, line,
circle, or polygon. objRef defines the parental object that limits
the point's domain. number specifies the relative position of the
point along this parental object's domain.
If the parent is a circle, number specifies an angle in
radians.
If the parent is a line, ray, or segment, numberspecifies a
proportion of the distance between the first and second point that define
the parent. Thus
Point on object(1, 0.50);
defines either the point on a circle at -28.6 degrees, if object#1 in
the construction is a circle, or the midpoint of object#1, if the object#1
is a segment.
JavaSketchpad allows users to drag a Point on Object to new
locations on its parental object.
5.1.5 Intersect (objRef1, objRef2);
Defines the single point of intersection between two linear objects.
Both objRefs must refer to segments, rays, or lines.
5.1.6 Intersect1 (objRef1, objRef2);
Defines one point of intersection between a circle objRef2 and
objRef1, which may be a circle, segment, ray, or line.
5.1.7 Intersect2 (objRef1, objRef2);
Defines the other point of intersection an object and a circle; i.e.,
Intersect2 returns the point of intersection that is not defined by
Intersect1.
5.1.8 PlotXY(objRef1, objRef2, objRef3);
Defines the point on the coordinate system objRef2 specified
horizontally by the value of measurement objRef3 and vertically by
the value of objRef1. That is, PlotXY() plots the point
(objRef3, objRef1) on objRef2.
5.1.9 UnitPoint(objRef1, num);
Defines a draggable point initially located num pixels to the
right of the point specified by objRef1.
JavaSketchpad allows a unit point to be dragged only to the
right of its objRef1 parent. Thus, a UnitPoint construction is a
convenient way of defining a point "to the right of an origin." If you
then construct a coordinate system by the Origin&UnitPoint
construction, using objRef1as the origin and the constructed unit
point as the coordinate system's unit, the unit point will always remain
at (1, 0) regardless of where it is dragged.
SquareUnitPoint(objRef1);
Defines the second UnitPoint relative to the UnitPoint specified by objRef1. This point is not draggable.
RectangularUnitPoint(objRef1, num);
Defines a draggable point initially located num pixels above the point
the UnitPoint specified by objRef1 refers to.
JavaSketchpad allows a second unit point to be dragged only above
the parent of the unit point objRef1. Thus, a RectangularUnitPoint construction is a
convenient way of defining a point "above an origin." If you
then construct a coordinate system, the rectangular unit point will always remain
at (0, 1) regardless of where it is dragged.
5.1.10 DriverPoint(num1, num2);
Defines a point with no parents at an arbitrary location in the plane.
num1 and num2 define the (x, y) position of that point
relative to the pixel coordinate system of the applet's window.
JavaSketchpad allows users to drag DriverPoints to new locations
in the applet's window. Unlike free Points, however, it also allows
external processes to request the name of, and set the location of,
DriverPoints via inter-applet communication. For inter-applet
communication purposes, the name of a DriverPoint is its label, which
should be assigned via the label formatting tag to any DriverPoint
appearing in a construction.
5.1.11 Other
See Transformations
for constructions that create points as transformed images of other
points.
5.2 Constructions That Create Straight
Objects
5.2.1 Segment (objRef1, objRef2);
Defines a segment connecting any two point objects.
5.2.2 Ray (objRef1, objRef2);
Defines a ray between any two point objects. objRef2 is the foot
of the ray; objRef1 defines the direction in which the ray
points.
5.2.3 Line (objRef1, objRef2);
Defines a line passing through any two point objects.
5.2.4 Perpendicular (objRef1, objRef2);
Defines line perpendicular to segment, ray, or line objRef1
passing through point objRef2.
5.2.5 Parallel (objRef1, objRef2);
Defines line parallel to segment, ray, or line objRef1 passing
through point objRef2.
5.2.6 HorizontalAxis(objRef1, objRef2);
Defines the horizontal axis with origin objRef1 and UnitPoint objRef2.
AxisX(objRef);
Defines the horizontal axis associated with the coordinate system
objRef.
5.2.7 VerticalAxis(objRef1, objRef2);
Defines the vertical axis with origin objRef1 and SquareUnitPoint or RectangularUnitPoint objRef2.
AxisY(objRef);
Defines the vertical axis associated with the coordinate system
objRef.
5.2.9 Other
See Transformations
for constructions that create straight objects as transformed images of
other straight objects.
5.3 Constructions That Create Interiors
Note: When a JavaSketch contains multiple overlapping interiors, the
order in which they are drawn is not explicitly defined. If this order is
important to your application, you can manually specify which interior is
drawn on top of which others by using the optional layer
format attribute.
5.3.1 Polygon (objRef1, objRef2 ...
objectReferenceN);
Defines a (shaded) polygon interior with ordered vertices specified by
the parental point objectReferences. There must be at least three
such objectReferences, but there can be more.
5.3.2 Circle interior(objRef}
Defines the (shaded) interior of circle objRef.
5.3.3 Other
See Transformations
for constructions that create interiors as transformed images of other
interiors.
5.4 Constructions That Create Circles
5.4.1 Circle (objRef1, objRef2);
Defines a circle centered at point objRef1 passing through point
objRef2.
5.4.2 Circle by radius (objRef1, objRef2);
Defines a circle centered at point objRef1 with a radius equal
in length to segment objRef2.
5.4.3 Other
See Transformations
for constructions that create circles as transformed images of other
circles.
5.5 Constructions
That Transform Geometric Objects
Certain objectNames correspond to constructions that create the
transformed image of some geometric pre-image object. The constructed
image is the same type of object as the pre-image, and so depending on the
type of the pre-image object, these constructions can create points, rays,
lines, segments, circles, or interiors.
JavaSketchpad cannot construct the transformation of buttons,
measurements, images, or loci.
5.5.1 Reflection (objRef1, objRef2);
Defines the image of any objRef1 reflected across the segment,
ray, or line objRef2.
5.5.2 Dilation (objRef1, objRef2, num);
Defines the image of any objRef1 dilated with respect to center
point objRef2 by a scaling factor of num. If
num>1.0, the scaling is larger, if num is less than 1,
its scaled image is smaller.
5.5.3 Dilation/SegmentRatio (objRef1, objRef2,
objRef3, objRef4);
Defines the image of any objRef1 dilated with respect to center
point objRef2 by the ratio of lengths of segment objRef3 to
segment objRef4.
5.5.4 Dilation/3PtRatio (objRef1, objRef2, objRef3, objRef4,
objRef5);
Defines the image of any objRef1 dilated with respect to center
point objRef2 by the signed ratio implied by the distances between
points objRef3, 4, and 5. If these three points are A, B,
and C, respectively, the three-point ratio implied by them is
|AC|/|AB|.
5.5.5 Dilation/MarkedRatio (objRef1, objRef2, objRef3)
Defines the image of any objRef1 dilated with respect to center
point objRef2 by the scaling factor determined by measurement
objRef3.
5.5.6 Rotation (objRef1, objRef2, num);
Defines the image of any objRef1 rotated around center point
objRef2 by the radian angle specified by num.
Note that num must be specified in radians even if the applet's
parameters request that the applet display angle measurements in
degrees to the user.
5.5.7 Rotation/MarkedAngle (objRef1, objRef2,
objRef3, objRef4, objRef5);
Defines the image of any objRef1 rotated around center point
objRef2 by the directed angle implied by the three points
objRef3-objRef4-objRef5.
5.5.8 Rotation/MeasuredAngle
(objRef1, objRef2, objRef3);
Defines the image of any objRef1 rotated around center point
objRef2 by the directed angle given by the measurement (or
calculation) objRef3.
5.5.9 Translation (objRef1, num1, num2);
Defines the image of any objRef1 translated by the Cartesian
offset (delta-X, delta-Y) specified by (num1, num2).
5.5.10 VectorTranslation (objRef1, objRef2,
objRef3);
Defines the image of any objRef1 translated by the vector
implied by two points objRef2 -> objRef3. objRef2
is the foot of the vector, and objRef3 is its tail.
5.5.11 Translation/FixedAngle/MarkedDistance (objRef1, objRef2,
num);
Defines the image of any objRef1 translated by the distance
expressed by measurement objRef2 in the direction expressed by
num radians.
5.5.12 PolarTranslation (objRef1, num1, num2);
Defines the image of any objRef1 translated by the Cartesian
offset specified by (num1, num2). This is a synonym for
Translation(), rather than a unique constructor of its own. (Desktop
Sketchpad converts all PolarTranslations by constant distance and
angles into Cartesian offsets before exporting.)
5.5.13 Translation/MarkedAngle/FixedDistance (objRef1, objRef2,
num);
Defines the image of any objRef1 translated by the distance
expressed by num in the direction expressed by angle measurement
objRef2.
5.5.14 Translation/MarkedAngle/MarkedDistance (objRef1, objRef2,
objRef3);
Defines the image of any objRef1 translated by the distance
expressed by distance measurement objRef3 in the direction
expressed by angle measurement objRef2.
5.6 Constructions That Create Images
5.6.1 Image (num1, num2, string);
Defines a rectangular picture image positioned in the plane at the (X,
Y) location specified by (num1, num2). string specifies the
URL of the image relative to the codebase containing the JSP applet used
by this Construction. (Note that standard security rules, as enforced by
many servers, may prevent you from accessing images outside of the JSP
directory by "../xyz.gif"-style relative URLs. Instead, place your images
inside the JSP folder, or inside a subdirectory. Assuming xyz.gif is
stored inside a directory titled "Images" instead the JSP directory, you
would use a URL such as "images/xyz.gif".)
Example:
Image(0, 0, 'euclid.gif');
This example creates an image object (a picture of Euclid assumed to be
stored in the server's JSP directory) with its upper-left corner located
at the upper-left corner of the applet window.
5.6.2 ImageOnPoint(objRef1,
string);
Defines a rectangular picture image in the plane with an upper-left
corner specified by the point objRef1. string specifies the URL of
the image relative to the codebase containing the JSP applet. The width
and height of the image are determined by the size of the picture
itself.
Example:
ImageOnPoint(1, 'euclid.gif');
This example creates an image object (a picture of Euclid assumed to be
stored in the server's JSP directory) with its upper-left corner located
at the position of object#1, a geometric point.
5.6.3
ImageBetweenPoints(objRef1, objRef2, string);
Defines a rectangular picture image in the plane with a location and
size determined by the smallest rectangle including points objRef1
and objRef2. string specifies the URL of the image relative
to the codebase containing the JSP applet.
5.7 Constructions That Create
Measurements
All measurements take a variable number of objectReferences, followed
by two numericConstants and a string. That is, an example measurement
construction looks like this:
{objName}({objectReferences},
numX, numY,
string);
For any measurement, numX and numY indicate the position
of that measurement on the coordinate plane (i.e., the coordinates of the
baseline of the first character of text), and string represents the
prefatory text which should appear with the reported value of the
measurement.
Example:
Length(5, 10, 50, 'Length = ');
Constructs the length of (segment) object#5 and positions it at (10,
50). The measurement will appear as in the following example:
Length = 13.2
In the individual constructions listed in this section, descriptions of
numX, numY, and string are not repeated for each
construction.
External processes interacting with a JavaSketch can request the value
of a given measurement through inter-applet communication. When doing so,
they request the value by name, where the name of a given
measurement is its prefatory text. When designing sketches for
inter-applet communication purposes, you may wish to verify that each of
your measurements has a distinct name so that external processes can
reference them uniquely.
External processes may also request a list of the names of measurements
in a sketch that are suitable for external inspection. By default,
JavaSketchpad will provide a list of all measurements in your
construction. You may suppress a given measurement from being listed as
available for inspection by including an underscore character ( _ ) at the
beginning of its prefatory text. If you're designing sketches for
inter-applet communication, you may wish to designate measurements that
contain "intermediate" or "uninteresting" values as unavailable for
external inspection.
5.7.1 Length(obj1, numX, numY,
string);
Constructs a measurement of the length of segment obj1.
5.7.2 Angle(obj1, obj2, obj3, numX,
numY, string);
Constructs a measurement of the angle implied by the three points
obj1, obj2, and obj3, with obj2 being the
vertex of the angle. The angle will be reported as either a directed or an
undirected angle, depending on the setting of the global DirectedAngles
parameter.
5.7.3 Perimeter(obj1, numX, numY, string);
Constructs a measurement of the perimeter of polygonal interior
obj1.
5.7.4 Circumference(obj1, numX, numY, string);
Constructs a measurement of the circumference of circle or circle
interior obj1.
5.7.5 Radius(obj1, numX, numY, string);
Constructs a measurement of the radius of circle or circle interior
obj1.
5.7.6 Area (obj1, numX, numY, string);
Constructs a measurement of the area of the circle, circle interior, or
polygon interior obj1. Note that the area is reported in square
distance units.
5.7.7 Slope (obj1, numX, numY, string);
Constructs a measurement of the slope of straight object
obj1.
5.7.8 Distance(obj1, obj2, numX, numY,
string);
Constructs a measurement of the distance between obj1 and
obj2. obj2 must be a point, obj1 may be either a
point or a straight object, in which case the distance is reported as the
minimum (perpendicular) distance between point obj2 and the
extended line containing obj1.
5.7.9 Ratio/Segments (obj1, obj2, numX, numY,
string);
Constructs a measurement of the ratio of the length of segment
obj1 to the length of segment obj2. That is, this
construction measures |obj|/|obj2|.
5.7.10 Ratio/Points (obj1, obj2, obj3,
numX, numY, string);
Constructs a measurement of the three-point ratio implied by points
obj1, obj2, and obj3. If these points are A, B, and C,
respectively, then the three-point ratio is |AC|/|AB|.
5.7.11 Coordinates(obj1, obj2, numX, numY, string);
Constructs a measurement of the ordered pair of coordinates
representing point obj1's location with respect to the coordinate
system obj2.
5.7.12 Calculate(numX, numY, prefixStr, exprStr)
(objRef1, ..., objRefN);
Constructs a measurement of the value of a calculated expression.
numX, numY, and prefixStr are the standard left and top
coordinates and prefix string of every measurement object; exprStr
contains a representation of the expression to calculate, and
objRef1 through objRefN are object identifiers of any other
measurement objects the value of which act as components of the
expression.
The exprStr expression is expressed in reverse Polish notation
(RPN), in which arithmetic operators follow their operands. RPN eliminates
the need for parentheses, because the order of evaluation is strictly
left-to-right. Thus "(1+2)/3" can be phrased in RPN as "1 2 + 3 /".
Valid tokens within exprStr include:
- numeric constants. Any real number can be expressed, with an
optional preliminary negative sign (for negative numbers) and an
optional single decimal point (for expressing non-integer values). A
numeric constant may include a terminal space to delimit it in
circumstances where two numeric constants are adjacent.
- +, -, /, *. These operators perform
their standard arithmetic operation: addition, subtraction, division,
and multiplication.
- ^: This operator performs exponentiation.
- !: This operator performs unary negation.
- @xxxx: This operator applies a predefined function.
xxxx is a four-character sequence indicating the function, and may be
one of the following: sin_ (sine), cos_ (cosine),
tan_ (tangent), abs_ (absolute value), sqrt (square
root), ln__ (natural log), rond (rounding), trnc
(truncation toward zero), sgn_ (signnum), asin (arcsine),
acos (arccosine), atan (arctangent), or log_
(base-10 logarithm). NB: JavaSketchpad trig functions take arguments in radians.
- x where x is in {A-Z}. This operand substitutes
the value of another measurement in the sketch: A corresponds to
measurement objRef1, B corresponds to measurement
objRef2, etc. It is an error to pass an operator that does not
have a corresponding objRef; i.e., to refer to C when you
only supply two objRefs in the construction (implicitly, A
and B).
- #xy where x is in {A-Z} and y is
in {1-9}. This operand substitutes the value of component
y of a vector-based measurement x. x refers to an
objRef according to the same rules above (i.e., A is
objRef1, B is objRef2, etc.). Parent objRefx
must be a vector-based measurement: In DR4 of JavaSketchpad, the
only vector-based measurement is the Coordinate pair. y indicates
the component of the vector to isolate. In DR4, the only legal values
for y are 1 and 2: 1 indicates the
x-component of a coordinate pair, 2 indicates the y-component of
that pair.
Examples:
Calculate(10, 10, 'Sum is ','AB+C+') (5, 6,
7);
Calculates the sum of measurement objects #5, 6, and 7 in the sketch,
and positions their sum at (10, 10) on the coordinate plane.
Calculate(20, 20, 'Distance is ','#A1#B1-2^#A2#B2-2^+@sqrt') (8,
9);
Calculates the Euclidean distance (sqrt[dX^2+dY^2]) between the two
coordinate pair measurements referenced as objects #8 and 9 in the
sketch.
Note that a space character may be used inside exprStr to
delimit individual tokens. This allows you to express one plus three as '1
3+' where '13+' would be interpreted as thirteen plus (whatever preceded
it).
Note also that the objRef list must not be empty, even if no
tokens in the expression refer to object references (i.e., even if the
expression's value is constant). This is a limitation of DR4, and will be
fixed in the next release.
5.7.13 Parameter(initialValue, numX, numY, prefixStr)
Constructs a measurement of an externally-specified value. When a
Parameter is first created, it will have a value of initialValue.
It will retain this value until the value is explicitly changed by an
external process using inter-applet communication. You can think of
Parameters as "free measurements" or as constants whose values are not
known until run-time, and derive other measurements (calculations) or
geometric objects based on Parameter values. When an external process
changes a Parameter, your derived measurements and objects will change as
well.
5.8 Constructions That Create Buttons
Action button constructions take a variable number of parameters, but
each of them include parameters numX, numY, and
string with the same interpretation as for measurements:
numX and numY determine where the action button is placed on
the coordinate plane (as the upper-left corner of the action button), and
string indicates the title of the action button.
In the individual constructions listed in this section, descriptions of
numX, numY, and string are not repeated for each
construction.
Additionally, action buttons may take two or more parenthesized lists
of parameters. The meaning of separate parameter lists is described in the
subsections below.
Example:
ShowButton(5, 10, 'Show Triangle') (1, 2, 3);
Constructs an action button titled "Show Triangle" located at (5, 10)
on the coordinate plane. of (segment) object#5 and positions it at (10,
50). In this example, pressing the button will cause objects#1, #2, and #3
in the construction to be shown if they're currently hidden.
Buttons can also display arbitrary images—.gif or .jpg files—rather
than text titles if you specify the Image
format attribute.
External processes interacting with a JavaSketch can request that
actions be executed through inter-applet communication. When doing so,
they specify the action by name, where the name of a given action
is its title. When designing sketches for inter-applet communication
purposes, you may wish to verify that each of your action buttons has a
distinct name so that external processes can reference them uniquely.
External processes may also request a list of the names of actions in a
sketch that are suitable for external inspection. JavaSketchpad
will provide a list of all actions in your construction (including ones
marked "hidden").
5.8.1 ShowButton(numX, numY, string)(obj1, obj2 ...
objN);
Constructs an action button that, when pressed, shows
obj1-objN if they are currently hidden. N must be at least
one. The action button has no effect if all of its objRefs are
already showing. See the previous section for an example of a ShowButton
construction.
5.8.2 HideButton (numX, numY, string)(obj1, obj2 ...
objN);
Constructs an action button that, when pressed, hides
obj1-objN if they are currently showing. N must be at least
one. The action button has no effect if all of its objRefs are
already hidden.
5.8.3 MoveButton(numX, numY, numZ, string)(obj1a, obj1b,
obj2a, obj2b ... objNa, objNb);
Constructs an action button that, when pressed, moves all points
objXb to their corresponding destinations determined by points
objXa. N must be at least one, meaning that the second argument
list (of pairs of moving points and destination points) must contain at
least two objRefs. If more than one pair is present (i.e., if more
than one point is moving), JavaSketchpad synchronizes all moving
points so they arrive at their destination simultaneously. numZ
indicates the speed, in pixels per frame, at which the slowest
moving point should travel. (This will be the point that is furthest from
its destination among all pairs of points and destinations.)
Example:
MoveButton(10, 0, 2.5, 'Move')(1, 8, 1, 5);
Creates an action button (located at (10,0), titled "Move") that moves
the point that is object#8 in the construction toward the point that is
object#1, while simultaneously moving the point that is object#5 in the
construction to the same destination. If the two points have to travel at
different speeds to reach their destinations, the slower of the two will
travel at 2.5 pixels/frame. (JavaSketchpad uses "pixels/frame"
instead of "pixels/second" to specify speeds, because visual
continuity—jumps between successive frames of animation—is more important
than temporal rigidity. Different Web browsers operate under sufficiently
different workloads and ambient conditions that attempt to specify
constant velocities are sure to fail.)
The construction is in error if any objXb (i.e., any moving
point) is not a free point or a point-on-object.
5.8.4 AnimateButton(numX, numY, string)(obj1a, obj1b,
obj2a, obj2b ... objNa, objNb)(num1, num2 ...
numN)(flag1Num1, flag1Num2 ...
flag1NumN)(flag2Num1, flag2Num2 ...
flag2NumN);
Creates an action button that, when pressed, animates all points
objXa along paths objXb. N must be at least one, meaning
that the objRefs parameter list must contain at least two entries.
The num parameter list and the two flagNum parameter lists
must contain exactly half as many entries as the objRefs parameter
list.
In the current release of JavaSketchpad, moving points can
travel along paths (objXb's) that are either circles or straight
objects (segments, rays, and lines). When traveling along rays and lines,
JavaSketchpad uses some arbitrary portion of the straight object as
its (finite) animation interval.
The num parameter list specifies the speed, in pixels/frame, of
each animating point. Thus numX is the speed at which objXa
travels along objXb.
The flag1Num parameter list specifies whether the animation
should occur "once only" or whether it should repeat indefinitely.
Possible values are 0 (repeat indefinitely) and 1 (stop after one tour of
the path). Points that travel paths "once only" make one circuit of their
path and then stop. Thus flag1NumX should be 0 if objXa
should repeatedly animate along path objXb.
The flag2Num parameter list indicates the motion associated with
each animated point. Possible values are 0 or 1, though the interpretation
of the value depends on the type of path. For circular paths, a value of 0
indicates clockwise motion and a value of 1 indicates counter-clockwise
motion. For linear paths, a value of 0 indicates "back and forth" motion
(oscillation along the interval of animation), and a value of 1 indicates
"one way" motion (proceeding always in the same direction from one end of
the interval to the other, and "wrapping" back from the far end to the
nearer one.) Note that for linear paths, you cannot combine "once only"
and "back and forth:" Any animation that is once only on a linear path
will always have "one way" motion.
Example:
AnimateButton(10, 0, 'Animate') (4, 3) (2.5) (1)
(0);
Constructs a button (located at (10,0), titled "Animate") that, when
pressed, moves point object#4 along the path of object#3 at 2.5
pixels/frame, stopping when the point has made one complete tour of the
path.
The construction is in error if any objXa—i.e., any moving
point—is not a free point or a point-on-object.
5.8.5 SimultaneousButton(numX, numY,
string)(objRef1, objRef2 ... objRefN);
Creates an action button that, when pressed, causes the several actions
specified by buttons objRef1..objRefN to start or stop. Use
SimultaneousButtons to consolidate multiple action buttons (which may be
hidden) into a single (visible) clickable button.
5.9 Constructions That Create Coordinate
Systems
Coordinate systems in JavaSketchpad that appear with the
(default) thin formatting attribute appear as "dot paper"—lattices of
regularly-spaced dots. Coordinate systems that have an explicit
"thick" formatting attribute appear as "grid paper" with
regularly-spaced grid lines. This DR4 release of JavaSketchpad only
supports display of rectangular grids, not of polar ones.
5.9.1 Origin&Unit(obj1, obj2);
Defines a coordinate system centered at point obj1 with a unit
length determined by the distance from obj1 to point
obj2.
5.9.2 UnitCircle(obj1);
Defines a coordinate system centered on circle obj1 with a unit
length determined by the radius of obj1.
5.9.3 CoordSysByAxes(obj1, obj2);
Defines a coordinate system by the HorizontalAxis obj1 and the
VerticalAxis obj2.
5.10 Constructions That Create Loci
5.10.1 Locus(obj1, obj2, obj3, num);
Constructs the locus of obj1 as point obj2 moves along
the path determined by obj3. JavaSketchpad devotes
num samples to the representation of the locus; higher values of
num correspond to more accurate approximations of the locus, but
take more time and computer memory to process.
This DR4 release of JavaSketchpad only supports the locus of
points, rays, lines, and segments, and only when defined with straight
objects, circles, or polygon as their paths. That is, obj1 must be
a point or a straight object, and obj3 must be a circle, straight
object, or polygon. If obj3 is a polygon, the perimeter of that
polygon determines the path of obj2.
A locus construction is in error if obj2 is not a point that can
be freely dragged (constructed either as a free point or a
point-on-object).
5.11 Constructions That Create
Captions
5.11.1 FixedText(numX,
numY, string);
Creates a caption displaying string at the fixed coordinates
(numX, numY) in the applet window.
5.11.2 PeggedText(objRef1,
objRef2);
Creates a caption with text identical to that of objRef2, which
must be either a measurement or another caption, located at the position
of the geometric point specified by objRef1.
5.11.3 ConcatText(numX,
numY)(objRef1, objRef2 ... objRefN);
Creates a caption located at the fixed coordinates (numX, numY)
in the applet window, displaying text composed by concatenating the text
of objRef1 through objRefN. All of these objRefs must
be measurements or other captions.
6.0 Error Messages
DR4 of JavaSketchpad does not give detailed error messages when
it encounters invalid constructions. Note that invalid constructions can
occur both when an {objectName} is misspelled or unknown, but also
when an object definition is logically invalid. For instance, the
definition
Perpendicular (1, 3);
may be valid, if object#3 is a point and object#1 a line, ray, or
segment, but is invalid if object#1 is a circle. Any invalid syntax or
geometry in a construction will prevent the applet from starting.
When a JavaSketchpad error occurs, the applet attempts to display the relevant Java error in the applet window (instead of your sketch geometry). If the error relates to the syntax problems with the Construction parameter, the error message should include a portion of Construction context indicating where the error occurred.
If nothing shows up in the JavaSketchpad applet window and you believe an error has occurred, check to see if your Web browser supports a "Java Console," "Java Message Log," or "Java Error Window." If so, you might want to inspect the error messages there to see if they help you identify the portion of your construction that led to the error.
7.0 Revision History
25-Feb-02. Revised to describe new JSP4 functionality, including:
- New object constructors (ImageOnPoint,
ImageBetweenPoints,
SimultaneousButton,
FixedText,
PeggedText,
ConcatText,
Rotation/MeasuredAngle)
- Revised PointOnObject
to also accepts polygonal domains
- New Layer
format now allows manual specification of which polygon is "on top"
- New Image
format now allows buttons to display a .gif or .jpg rather than a
textual title
- New text
style formats now allow various font typography settings
24-Feb-02. Added table of named colors and fixed several errors in
existing grammar statements. Thanks to Nick Donaldson and Michael Rundel
for their comments.