home : javasketchpad : dr grammar

JavaSketchpad Developer's Construction Grammar

0.0 Contents

• Legal Notices and Restrictions
• Purpose of the Grammar
• Applet Invocation
• Grammar Overview
• Legal Constructions
  • Points
  • Straight Objects
  • Circles
  • Interiors
  • Transformations
  • Images
  • Measurements
  • Buttons
  • Coordinate Systems
  • Loci
  • Captions
• Errors
• Document Revision History

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 and 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 or 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 layer 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')[bold, size(24), 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 num2 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, number specifies 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.

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 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

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 objRef2, which must be either a segment or a distance measurement.

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 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, num2);

Defines the image of any objRef1 translated by the distance expressed by num1 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" inside 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. 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 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 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.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

5-Sep-03. Corrected color specification order in 4.4.2; documented possible measurement distance references in 5.4.2; updated 6.0 to reflect recent applet error reporting changes; noted in 5.7.12 that trig functions always work in radians..

25-Feb-02. Revised to describe new JSP4 functionality, including:

1. New object constructors (ImageOnPoint, ImageBetweenPoints, SimultaneousButton, FixedText, PeggedText, ConcatText, Rotation/MeasuredAngle)
2. Revised PointOnObject to also accepts polygonal domains
3. New Layer format now allows manual specification of which polygon is "on top"
4. New Image format now allows buttons to display a .gif or .jpg rather than a textual title
5. New text style formats now allow various font typography settings

This document is still missing the revised grammar for JSP4 coordinate systems and axes.

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.