JavaSketchpad Construction Grammar

Developer's Release 3

Rev. 6 March 2000

Nick Jackiw - njackiw@keypress.com

0.0 Contents

Readers already experienced with JSP's grammar can view the highlights of what's new in DR3.


1.0 Legal Notices and Restrictions

Entire contents Copyright (C) 1997-2000 by Key Curriculum Press Inc. Right is granted to freely use DR1, DR2, and DR3 of the JavaSketchpad applet in your own web pages, provided you do so for non-commercial use only. (Other permissions or rights to JavaSketchpad require a written agreement letter from Key Curriculum Press---contact the author for more info.)


2.0 Purpose

This document describes the mechanism by which web pages interact with the JavaSketchpad applet, and describes the linguisitic grammar you must use to view arbitrary geometric constructions with the JavaSketchpad applet.

This document describes the current release of the JavaSketchpad applet (DR3). The grammar specified here isn't guaranteed to remain unchanged in the final release of JavaSketchpad. However, it will continue to work with DR3 of the applet, so you can safely publish web pages using this grammar now, provided you ensure that your web server also publishes DR3 of the JavaSketchpad applet. With luck, the final JavaSketchpad grammar will maintain backward compatibility with this DR3 grammar; if so, web pages you create now will continue to work even if you update your server to publish the final, improved version of the applet.


3.0 Applet Invocation

JavaSketchpad is implemented by a set of Java .class files which 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="JSPDR3.JAR" WIDTH=200 HEIGHT=150 ALIGN=left>
<PARAM NAME=Offscreen VALUE=1>
<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 which 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 Java Sketchpad.)

The <APPLET> tag has several sub-parameters which 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 which 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 "JSPDR3.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 which extends the specified WIDTH and HEIGHT by one pixel.

3.2.3 Construction parameter

The Construction parameter specifies the complete dynamic geometry construction which 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.

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 blue component, and the third, green.

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.

In this release of JavaSketchpad, 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.


5.0 Legal Object Constructions

This section lists all {objectNames} currently known to the current release 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 Java sketches, 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, or circle. 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 which 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.

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 objRef2 passing through point objRef1.

5.2.6 AxisX(objRef)

Defines the horizontal axis associated with the coordinate system objRef.

5.2.7 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

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 |AB|/|AC|.

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 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.9 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.10 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.11 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.12 Translation/MarkedAngle/FixedDistance (objRef1, objRef2, num2);

Defines the image of any objRef1 translated by the distance expressed by num1 in the direction expressed by angle measurement objRef2.

5.5.13 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.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 which 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 which 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:

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 DR3, 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.

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 which 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 which, 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 which, 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 which, 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 which is object#8 in the construction toward the point which is object#1, while simultaneously moving the point which 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 work-loads and ambient conditions that attempts 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 which, 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 counter-clockwise motion and a value of 1 indicates 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 which 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") which, 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.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 DR3 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.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 DR3 release of JavaSketchpad only supports the locus of points, rays, lines, and segments; and only when defined with straight objects or circles as their paths. That is, obj1 must be a point or a straight object, and obj3 must be a circle or straight object.

A locus construction is in error if obj2 is not a point which can be freely dragged (constructed either as a free point or a point-on-object).


6.0 Error Messages and Support

DR3 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#1 is a point and object#3 a line, ray, or segment, but is invalid if object#3 is a circle. Any invalid syntax or geometry in a construction will prevent the applet from starting.

If nothing shows up in the JavaSketchpad applet window when you use a browser to open a web-page with a manually-specified Construction, 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 which portion of your construction is invalid.

Unfortunately, at this point, Key Curriculum Press cannot provide technical support to help you debug manually-specified Constructions, so use this grammar at your own risk.

When the final release of JavaSketchpad is available, we will of course provide full technical support.


7.0 What's New in DR3

DR3 is primarily a performance and bug-fix release, with a small amount of new functionality thrown in to keep things interesting. This section lists corrections made in DR3 and highlights DR3 additions to the JavaSketchpad grammar and applet functionality.

DR3 is backwards-compatible with DR2 and DR1; older sketches should continue to work as before. Neither DR2 nor DR1 is forwards-compatible, however. If you use the DR3 HTML Converter to create a JavaSketch, that sketch will require the DR3 version of the applet.

7.1 Bugs Fixed in JSP Applet

7.2 Bugs Fixed in HTML Exporter

7.3 New Constructions

Several new constructions have been added or documented for the first time:

7.4 New Inter-Applet Communication Functions

JavaSketchpad now supports inter-applet communication at the direct method invocation level (JSP_ExternIO interface), through explicit event wiring under the JavaBeans paradigm, and through implicit connectivity under the emerging Infobus-based ESCOT protocols. While this communication does not affect the construction grammar directly, two new constructions have been added to support external communication:

In addition, the semantics of several existing constructions have been changed to support inter-applet communication:

 


Return to the JavaSketchpad home.