Developer's Grammar

1.0 Legal Notices and Restrictions

Entire contents copyright © 2014 by McGraw-Hill Education. Right is granted to freely use DR1, DR2, DR3, DR4, and DR5/G2  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 McGraw-Hill Education for details.)

2.0 Purpose of the Grammar

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 version 5 release of the JavaSketchpad applet. This corresponds to Developer's Release 5 (DR5) and Grammar version 2 (G2). Grammar version 1 correponds to every version of JavaSketchpad released before GSP 5.00.

See the Document Revision History for a brief summary of what's new in DR5 and G2.

3.0 Applet Invocation

JavaSketchpad is implemented by a Java archive (.jar) file that lives on your Web server. Individual Web pages link to this file, 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.

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 subparameters that are discussed in this section.

3.1.1 CODE parameter

CODE indicates the name of the Java class to first load and should not be changed from "GSP.class."

3.1.2 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. Setting this to "." means that jsp5.jar should be located in the same directory as the HTML file. If your Web page is stored in a directory on the server other than the directory that contains the applet, provide a relative path that specifies how to find the JSP applet from the directory in which the Web page resides.

3.1.3 ARCHIVE parameter

ARCHIVE indicates the filename of a .jar archive. ARCHIVE should always be set to "jsp5.jar" for this release of JavaSketchpad.

3.1.4 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.1.5 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 pair, you specify inputs to the JavaSketchpad applet by using the tag. In general, this tag has the form

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. The value 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. The value 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:

Sets the background color of an applet to bright (full) red.

3.2.5 Font parameters

The current release of JavaSketchpad supports three separate default font appearances for measurements, labels, and action buttons. If a specific object that displays text does not specify its own, object-specific font appearance (see Text Style Formats), it inherits the corresponding appearance from one of these defaults. 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 four 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) indicates 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.

3.2.6.3 Scaling Factor parameter

The PixelsPerLengthUnit parameter indicates an inverse scaling factor to apply to all length measurements. The default unit of length in JavaSketchpad is the pixel. Setting PixelsPerLengthUnit to 96, for example, changes length measurements to report measurements in units of (approximately) one inch, since many monitors display 96 pixels per inch.

3.2.6.4 Precision parameter

The Digits parameter indicates the precision of calculations and measurements, with a whole number value used to determine the number of digits to display after the decimal point. The default is 3 digits, which is used if this parameter is not set or if the value is invalid.  Individual measurements may also override this global default by specifying their own Precision format; see section 4.4.13.

3.2.7 Minimum Grammar parameter

Certain features introduced into a version of JavaSketchpad may not work properly if an HTML sketch refers to an older version of the JSP applet. In this scenario, an error can be displayed rather than allowing the user to view a sketch that is only partially valid due to the outdated JSP. Note that the Grammar Version is different than Developer's Release (DR) and the current grammar for the JSP released with GSP 5.00 is 2. JSP applets released before GSP 5.00 using a grammar older than Grammar Version 2 will not detect this parameter and will simply attempt to display the sketch.

3.2.7.1 MinimumGrammarVersion parameter

The MinGrammarVersion is the minimum version of the grammar required to run the present JavaSketch. This value can be set by the developer in order to assure that the user is given an intelligible error if the HTML file is placed next to an outdated JSP applet. If the minimum Grammar Version is not met, the sketch will display an error requesting that the user upgrade to the latest version.

3.2.7.2 Grammar Version Error parameter

The text value of the GrammarVersionError parameter can be used to display a specific error beyond the generic text displayed by default when the minimum Grammar Version is not met.

3.2.8 Build Number parameter

Every release of the JSP applet has a unique build number associated with it, which is disctinct from the Grammar Version and the Developer's Revision. The ShowBuildNumber parameter indicates whether the build number of the JSP applet should (1) or should not (0) be displayed.

4.0 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];

the {objectName} is Segment, {objectArguments} is the list (3, 1), and {optionalFormats} is [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 JavaSketchpad is described below, in Legal Constructions.

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 is described below (Legal Constructions) . 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 complete construction example 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 Style formats

You may assign a line style to any ray, line, segment, or circle by specifying one of the following widths: hairline, thin, mediumLine, or thick. You may also specify one of the following patterns: dashed, dotted, or solid.

4.4.4 Point Style formats

The format of an individual point may be designated with one of the following styles: dot, small, mediumPoint or large.

Example:

Point(50, 100)[large];

creates a large point at (50, 100) on the coordinate plane.

4.4.5 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.6 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; suffixes 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.7 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 five 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.8 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.9 Traced formats

You may 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.10 Layer formats

You may specify that an object is drawn "on top" of other objects by changing its layer. By default, JavaSketchpad 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.11 Image formats

You may display a picture on the action button by specifying the URL of a picture or digital image (.gif or .jpg file)  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 picture relative to the codebase of the applet.

Example:

ShowButton(10,10,'unused')(1, 2, 3)[image('map.gif')];

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 a picture rather than a text title (due to the presence of the image format attribute). The picture displayed by the button is given by the file map.gif, which is located at the codebase of the JSP applet.

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

The justify formats justify the specified edge of text in relation to the coordinate position specified for text placement:

4.4.13 Precision formats

Each calculation or measurement may have its precision set with the "digits" specifier. This will designate the number of digits to be displayed beyond the decimal point.

Example:

Distance(1,2,14,24,'AB = ')[digits(10)];

displays the resulting distance to 10 digits past the decimal point. By default, the number of digits displayed if this value is not set, or if it is invalid, is determined by the global Precision parameter for the entire sketch. See 3.2.6.4

5.0 Legal 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 subsections, 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);

Defines a point whose domain is limited to a segment, ray, line, circle, polygon, function plot, or point locus. 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 not a circle, 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 PlotFixedXY (objRef1, num1, num2);

Defines a point that is fixed on the coordinate system objRef1. num1 and num2 define the (x, y) position and the point may not be dragged away from this location.

5.1.10 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.11 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. This deprecated construction behaves identically to the preferred Point() construction (described at 5.1.1). Older versions of JavaSketchpad allowed external processes to control the position of DriverPoints procedurally; however, due to browser limitations, this functionality now only appears in assemblages of JavaBeans.

5.1.12 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 a line perpendicular to segment, ray, or line objRef1 passing through point objRef2.

5.2.5 Parallel (objRef1, objRef2);

Defines a 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.8 Bisector (objRef1, objRef2, objRef3);

Defines the ray that bisects the minor angle implied by the three points objRef1, objRef2, and objRef3, with objRef2 designating the vertex of the angle.

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

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

5.5.14 Translation/MarkedAngle/MarkedDistance (objRef1, objRef2, objRef3);

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

5.6 Constructions That Colorize Geometric Objects

These constructions define a copy of a given object, with a variable color dynamically determined by the value of one or more parameters, measurements, or calculations in the sketch. The object to be colorized is objRef1, which is followed by one or three more objects depending on the type of colorization. In each case, num1 defines the lower limit of the parameter's domain, num2 defines the upper limit and num3 defines the behavior outside of the domain, where 0 is do not repeat, 1 is repeat one-way, and 2 is repeat bidirectionally. When using colorization, make sure that the uncolored original object (objRef1) is marked [hidden], since it will fully coincide with the dynamically-colored object produced by these constructions.

5.6.1 Colorized_Spectrum (objRef1, objRef2, num1, num2, num3);

Defines the color of an object based on a one-dimensional color spectrum defined by the value of objRef2.

5.6.2 Colorized_Grayscale (objRef1, objRef2, num1, num2, num3);

Defines the color of an object based on a grayscale shading from black to white defined by the value of objRef2.

5.6.3 Colorized_RGB (objRef1, objRef2,objRef3,objRef4, num1, num2, num3);

Defines the color of an object based on an RGB color model, where objRef2 defines the red, objRef3 defines the green, and objRef4 defines the blue of the resulting color.

5.6.4 Colorized_HSV (objRef1, objRef2,objRef3,objRef4, num1, num2, num3);

Defines the color of an object based on an HSV color model, where objRef2 defines the hue, objRef3 defines the saturation, and objRef4 defines the value of the resulting color.

5.7 Constructions That Create Pictures

5.7.1 Image (num1, num2, string);

Defines a rectangular picture or digital image positioned in the plane at the (X, Y) location specified by (num1, num2), where string specifies the URL of the picture relative to the codebase containing the JSP applet used by this construction.

Example:

Image(0, 0, 'euclid.gif');

This example creates a picture object (a picture of Euclid assumed to be stored next to the JSP applet)  with its upper-left corner located at the upper-left corner of the applet window.

(Note that standard security rules, as enforced by many servers, may prevent you from accessing pictures outside of the JSP directory by "../xyz.gif"-style relative URLs. Instead, place your pictures next to the JSP applet or inside a subdirectory.  Assuming xyz.gif is stored inside a directory titled "pictures" next to the JSP applet, you would use a URL such as "pictures/xyz.gif".)

5.7.2 ImageOnPoint (objRef1, string);

Defines a rectangular picture in the plane with an upper-left corner specified by the point objRef1, where string specifies the URL of the picture relative to the codebase containing the JSP applet. The width and height of the picture are determined by the size of the picture itself.

Example:

ImageOnPoint(1, 'euclid.gif');

This example creates a picture object (a picture of Euclid assumed to be stored next to the JSP applet)  with its upper-left corner located at the position of object#1, a geometric point.

5.7.3 ImageBetweenPoints (objRef1, objRef2, string);

Defines a rectangular picture in the plane with a location and size determined by the smallest rectangle including points objRef1 and objRef2, where string specifies the URL of the picture relative to the codebase containing the JSP applet.

5.8 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 that 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.

5.8.1 Length(obj1, numX, numY, string);

Constructs a measurement of the length of segment obj1.

5.8.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.8.3 Perimeter(obj1, numX, numY, string);

Constructs a measurement of the perimeter of polygonal interior obj1.

5.8.4 Circumference(obj1, numX, numY, string);

Constructs a measurement of the circumference of circle or circle interior obj1.

5.8.5 Radius(obj1, numX, numY, string);

Constructs a measurement of the radius of circle or circle interior obj1.

5.8.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.8.7 Slope (obj1, numX, numY, string);

Constructs a measurement of the slope of straight object obj1.

5.8.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.8.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.8.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.8.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.8.12 Abscissa(objRef1, objRef2, numX, numY, string);

Constructs a measurement of the abscissa of objRef1 defined on the coordinate system objRef2.

5.8.13 Ordinate(objRef1, objRef2, numX, numY, string);

Constructs a measurement of the ordinate of objRef1 defined on the coordinate system objRef2.

5.8.14 CoordinateDistance(objRef1, objRef2, objRef3, numX, numY, string);

Constructs a measurement of the coordinate distance between points objRef1 and objRef2 defined on the coordinate system objRef3. This distance is always measured in relation to the coordinate system and is not affected by the global PixelsPerLengthUnit parameter.

5.8.15 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.
• 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: currently, the only vector-based measurement is the Coordinate pair. y indicates the component of the vector to isolate. 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.
• @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.
• @fx: This operator applies to a function defined in the sketch. z is in {A-Z} and @fA refers to the function objRef1, @fB refers to the function objRef2, etc. See the Function construction for more details.

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.

Example:

Calculate(21,96,'f(p) = ','5 @fA')(4);

Calculates the value of f(5), where f is the function defined as object #4 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 be included, even if it is only an empty pair of parentheses.

5.8.16 Parameter(initialValue, numX, numY, prefixStr)

Constructs a numeric value. When a Parameter is first created, it will have a value of initialValue. 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. In JavaBean assemblages, external processes may change a Parameter's value; if so, any measurements and objects that depend on the Parameter will change as well.

5.9 Constructions That Create Buttons

Action button constructions take a variable number of parameters, but each of them includes 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 pictures—.gif or .jpg files—rather than text titles if you specify the Image format attribute.

5.9.1 ToggleVisibilityButton(numX, numY, string)(obj1, obj2 ... objN);

Creates an action button that will alternately hide and show the objects obj1-objN. N must be at least one. string may take the form 'Hide Object|Show Object,' in which case the portion preceding the pipe (|) will be displayed when the object is visible and the section following the pipe will be displayed when it is hidden.

5.9.2 ShowButton(numX, numY, string)(obj1, obj2 ... objN);

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

5.9.3 HideButton (numX, numY, string)(obj1, obj2 ... objN);

Creates 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. See the previous section for an example of a ShowButton construction.

5.9.4 MoveButton(numX, numY, numZ, string)(obj1a, obj1b, obj2a, obj2b ... objNa, objNb);

Creates 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 widely different workloads and ambient conditions; therefore, 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.9.5 AnimateButton(numX, numY, string)(obj1a, obj1b, obj2a, obj2b ... objNa, objNb)(num1, num2 ... numN)(flag1Num1, flag1Num2 ... flag1NumN)(flag2Num1, flag2Num2 ... flag2NumN);

Creates an action button that, when pressed, animates all points objXa along paths objXb. N must be at least one, meaning that the objRefs parameter list must contain at least two entries. The num parameter list and the two flagNum parameter lists must contain exactly half as many entries as the objRefs parameter list.

In the current release of JavaSketchpad, moving points can travel along paths (objXb's) that are either circles or straight objects (segments, rays, and lines). When traveling along rays and lines, JavaSketchpad uses some arbitrary portion of the straight object as its (finite) animation interval.

The num parameter list specifies the speed, in pixels/frame, of each animating point. Thus numX is the speed at which objXa travels along objXb.

The flag1Num parameter list specifies whether the animation should occur "once only" or whether it should repeat indefinitely. Possible values are 0 (repeat indefinitely) and 1 (stop after one tour of the path). Points that travel paths "once only" make one circuit of their path and then stop. Thus flag1NumX should be 0 if objXa should repeatedly animate along path objXb.

The flag2Num parameter list indicates the motion associated with each animated point. Possible values are 0 or 1, though the interpretation of the value depends on the type of path. For circular paths, a value of 0 indicates clockwise motion and a value of 1 indicates counter-clockwise motion. For linear paths, a value of 0 indicates "back and forth" motion (oscillation along the interval of animation), and a value of 1 indicates "one way" motion (proceeding always in the same direction from one end of the interval to the other, and "wrapping" back from the far end to the nearer one.) Note that for linear paths, you cannot combine "once only" and "back and forth": Any animation that is "once only" on a linear path will always have "one way" motion.

Example:

AnimateButton(10, 0, 'Animate') (4, 3) (2.5) (1) (0);

constructs a button (located at (10,0), titled "Animate") that, when pressed, moves point object #4 along the path of object #3 at 2.5 pixels/frame, stopping when the point has made one complete tour of the path.

The construction is in error if any objXa—i.e., any moving point—is not a free point or a point-on-object.

5.9.6 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.10 Constructions That Create Coordinate Systems

Coordinate systems in JavaSketchpad appear with regularly spaced grid lines. This DR5 release of JavaSketchpad only supports the display of rectangular grids, not polar ones.

5.10.1 CoordSysByAxes(obj1, obj2);

Defines a coordinate system based on the horizontal axis obj1 and the vertical axis obj2.

5.10.2 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.10.3 UnitCircle(obj1);

Defines a coordinate system centered on circle obj1 with a unit length determined by the radius of obj1.

5.11 Constructions That Create Functions

5.11.1 Function(numX, numY, string, exprStr)(objRef1, ..., objRefN);

Constructs a function, that may be graphed and evaluated at specific values when referenced from other calculations or functions. numX and numY are the coordinates where the location is displayed in the sketch, string is the string displayed at that location, and exprStr is a representation of the function in reverse Polish notation (RPN). See the description of valid tokens in an RPN expression under the Calculate construction for an explanation on how to create these expressions. Note that while string and exprString should correspond for ease of understanding the sketch by the end user, they do not have any inherent relation to each other. If a function seems to be working incorrectly, first make sure that that the RPN is valid and then assure that the string makes sense as a representation of the RPN expression.

Examples:

Function(14,24,'f(x) = x + 1','x 1 + ')()[black];

Creates the function f(x) = x + 1, which can be referred to by another calculation, function, or function plot.

Function(14,51,'g(x) = 2*f(x)','2 x @fA * ')(1)[black];

Creates a function defined by another function. Assuming that object #1 in the sketch is the previously defined function f(x) = x + 1, then this new function creates a function g(x) = s * f(x) = 2 * (x+1).

5.12 Constructions That Create Loci

5.12.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 DR5 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.12.2 FunctionPlot (objRef1, objRef2, num1, num2, num3, num4);

Constructs a function plot based on the function objRef1 on the coordinate system objRef2, with num1 samples, a domain ranging from num2 to num3 (in the domain's coordinate units), and a projection given by num4. The projection may be 0 (y = f(x)), 1 (x = f(y)), 2 (r = f(theta)), or 3 (theta = f(r)).

5.13 Constructions That Create Captions

5.13.1 FixedText(numX, numY, string);

Creates a caption displaying string at the fixed coordinates (numX, numY) in the applet window.

5.13.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.13.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 Errors

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 Document Revision History

1-May-10. Revised to describe DR5/G2 functionality, including:

1. New constructors (Function, FunctionPlot, ToggleVisibilityButton, Bisector,  PlotFixedXY, Abscissa, Ordinate, CoordinateDistance,  and Colorizations)
2. New parameters (PixelsPerLengthUnit, Digits, MinimumGrammarVersion,  GrammarVersionError,  and ShowBuildNumber)
3. Expanded and added formats (Line Style, Point Style, and Precision)

8-Dec-04. Deprecated references to JSP's Inter-Applet Communication model, since modern browsers now only support this paradigm in packaged assemblages of JavaBeans.

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.