Tool Authoring for Web Sketchpad

Tool authoring is done in Desktop Sketchpad (GSP). To create a tool, add a page to your GSP document, giving the new tool page a special name that instructs the WebSketchpad exporter to convert the page into a tool.

By default, tools are document-wide: If the document has multiple pages, the tools for that document will be accessible from every page.

WSP Tool Basics

When the user taps a WSP tool button, toolplay begins: The entire tool construction appears, with the givens highlighted and the productions faded. One given object glows to indicate that it’s the currently active given ready either to be matched to a sketch object or to be located in the sketch. The user can match the active given in any of these ways:

• Tap an existing sketch object of the same kind to match the active given to it.
• Tap in empty space to place the active given at the tapped location.
• Press and drag the active given, releasing it on the desired object or at the desired location.
• Press in empty space and begin dragging. The active given will follow your pointer, and you can release it on the desired object or at the desired location.
• If the active given is a point, tap or drag to an existing path object to place the active given on the path. (Path objects include segments, rays, lines, circles, arcs, perimeters of interiors, and point loci.)
• If the active given is a parameter, tap or drag to an existing value object to set the parameter to that value.

For tools with more than one given, you can choose to drag a different given instead of the currently active (glowing) given. Press and drag the given you want to match or plqce, and it immediately becomes the active given, allowing you to place it (by releasing in empty space) or to match it (by releasing on the desired object as described above).

Create Three WSP Tools

You can use GSP to create a web page with three WSP tools by following the directions below.

Create a WSP Compass Tool

Create a WSP Angle Tool

Create a WSP Circumference Tool

Tool Givens and Productions

WSP tools perform constructions involving two kinds of objects: givens (the independent objects on which the construction depends) and productions (the constructed objects that are produced based on the givens).

Specify the Roles of Given Objects

WSP supports four different roles for given objects. For simple, assumed, and constructible givens, identify the role by assigning a label that starts with one of these three keywords. (The keyword is optional for givenParent objects, which are identified automatically based on their constructible child.)

• A simple given (keyword: given) is an independent object that the user must place or match in the sketch. (The given points in the Segment and Measure Angle tools above are simple givens.) [More details…]
  A simple given must be an object that has no parents. For example, it might be an independent point, a parameter, an independent function, or an independent calculation. The label must begin with given, optionally followed by the sort ordersort order. If you want the given to appear with a label, insert a colon after the keyword and optional sort order. For instance, you might label a simple given point given2: A to indicate that it should be activated as the second given, and should be labeled A. Refer to Tool Object Labels below for more options for labeling tool objects. (A simple given calculation of 1+1 is a special case: it is automatically replaced by an empty calculation, enabling the sketch author to provide the tool user with a calculation they can fill in themselves.)
• An assumed given (keyword: assumed) is a labeled independent object that will be automatically matched to an already-existing sketch object that has the same label. [More details…]

  Like a simple given, an assumed given must be an object that has no parents. Because it’s matched by label, it must have a label, and the sketch into which the tool is played must already have an object of the same kind and with the same label. The tool object’s label must begin with assumed: followed by the label that will be used to find the existing sketch object to which the assumed given will be matched. For instance, you might use assumed: unit as the label of a distance parameter so that the tool’s construction uses the same unit value as other constructions in the sketch. Similarly you might use assumed: Center for a tool that rotates an object around a center point already designated in the sketch by the same label: Center.

  If the sketch does not contain an object to match the assumed given, the assumed given is placed in the sketch, using the same location (if a point) or the same value (if a parameter) as it had in the page that defines the tool. (Such an automatically-placed object can be used as an assumed object during later use of the same, or a different, tool.)

  If all givens for a tool are assumed, the tool is an auto-play tool and creates its productions instantly when the user taps the tool button.

  Objects such as captions and pictures do not have labels, and thus cannot be assumed givens. A coordinate system is a special case, handled automatically as an assumed given. There’s no need to specify that a coordinate system is assumed.

  If multiple objects in a sketch match the assumed given of a tool, the tool chooses the most recently-created of the matching objects. This makes it possible to create a tool that iterates by producing a new object with the same label as its assumed given. Each subsequent use of the tool will use as its assumed given the object just constructed by the previous use of that tool.

  Refer to Tool Object Labels below for more options for labeling tool objects.

• A constructible given (keyword: constructible) is a given tool object constructed from independent parents. Constructed objects like segments, circles, and polygons cannot serve as simple givens because they are not independent, but they can be used as constructible givens if their parent objects are independent. A constructible given can be placed or matched directly, or it can be placed or matched by its parents (referred to as givenParents). [More details…]

  You can use constructible givens to create a variety of tools that require given objects that are not independent. Examples include a Length tool that measures the length of its given segment, a Circumference tool that measures the circumference of its given circle, or an Area tool that measures the area of its given polygon. Though the constructible given is not independent, each of its givenParents must be independent and must have no children other than the constructible given itself.

  For example, to create a Circumference tool, you can

  When a tool’s constructible given is matched to an existing sketch object, the tool object’s givenParents are automatically matched to the parents of the existing sketch object. For example, if a tool has a constructible circle whose givenParents are a center point and a radius point, and the tool’s circle is matched to an existing sketch circle that also has a can be a constructible given, provided that its givenParents (the center and radius points) have no other children. However, the perpendicular bisector of a segment cannot be a constructible given, because its parent object is a segment, which is not an independent object and cannot serve as a givenParent. The user can place or match a constructible directly (by placing or matching the constructible itself) or parentally (by placing or matching its givenParents).

  To place or match the circle directly, the user (a) taps in empty space (thereby placing the constructible circle), or (b) taps an existing circle, or (c) drags the constructible circle to leave it in a new location or to match it to an existing circle.

  To place or match the circle parentally, the user first drags one of the constructible’s parents to match or place that parent. This action switches the constructible from direct to parental mode, and each of the remaining givenParents will become active in turn.

  After switching the constructible to parental mode, the user can still switch back to direct mode as long as long as one of the givenParents remains active.

  Refer to Tool Object Labels below for more options for labeling tool objects.
• A given parent (optional keyword: givenParent) is an independent object that has a constructible given as its only child. A givenParent does not normally require any special labeling at all. The givenParents of a tool’s constructibleGiven become active only when the tool user drags one of them instead of matching the constructible directly. [More details…]

  You can label constructibles and their givenParents as you would label other given objects. For instance, in a Reflect tool you might want to label the constructible as constructible: mirror, and you might want to label the two givenParents that define the mirror as M1 and M2. You could alternatively label these givenParents as givenParent: M1 and givenParent: M2, but there’s no need to specify the givenParent keyword, because the mirror’s role as a constructible automatically identifies its parents as givenParents.

  Web Sketchpad allows the tool user to switch back and forth between direct and parental matching. The default is direct matching of the constructible, but if the tool user instead drags one of the constructible’s parents, the tool switches to parental matching. Even after the switch to parental matching, the tool user can drag the constructible itself to switch back to direct matching.

  Refer to Tool Object Labels below for more options for labeling tool objects.

As you use a GSP page to define a WSP tool, note that the given objects of the resulting tool will include only independent objects whose role you have determined, either by providing the given object itself with a label that begins with one of the above keywords, or by identifying the given object’s only child as a constructible given. Any other constructions on the GSP page will not be included in the resulting WSP tool.

Set the Sort Order of Given Objects

When the user chooses a tool containing more than a single given, the tool’s given objects become active, one after the other. Sometimes (for instance, with a Line Tool), the order may not matter. In other cases (for instance, the Measure Angle Tool) it may be important; you might prefer the three given points to become active in a specific order: first the point-on-initial-side, then the point-vertex, and last the point-on-final-side. As the tool author, you can set this as the sort order by appending a number to each given object’s keyword, labeling the point-on-initial-side as given1, the point-vertex as given2, and the point-on-final-side as given3. [More details…]

Set the Displayed Labels of Given Objects

The keywords you use on the GSP source page for a tool do not appear when the WSP user eventually activates the tool. To specify a label that you want the tool user to see, append a colon to the given keyword (and sort-order number, if present), followed by the label you want to provide. See the section below on Labeling Tool Objects for more details on labeling the givens and productions of a tool.

Tool Object Labels

• A simple given does not depend on any other object, and must be placed or matched by the user during toolplay. To identify a You given object with a label that starts with given. Simple givens may be points, parameters, and other text objects such as functions and calculations. (To qualify as a given object, a function or calculation cannot depend on any other object. A calculation of 1+1 is a special case: it is automatically replaced by an empty calculation to provide a way for the sketch author to include a calculation to be filled in by the tool user.)
• Assumed givens are given objects that are matched automatically at the start of toolplay. They are created by labeling the intended assumed object with a label of the form assumed: <label>, where <label> is replaced by the label of the sketch object to which the assumed tool object should be matched. Assumed givens can only be matched to a sketch object that’s of the same kind and that has the matching label. If the sketch does not contain an object to match the assumed given, the assumed given is placed in the sketch, using the same location (if a point) or the same value (if a parameter) as it had in the page that defines the tool. (Such an automatically-placed object can be used as an assumed object during later use of the same, or a different, tool.) If all givens for a tool are assumed, the tool is an auto-play tool and creates its productions instantly when the user taps the tool button. (Objects such as captions and pictures do not have labels, and thus cannot be assumed givens. A coordinate system is a special case, handled automatically as an assumed given. There’s no need to specify that a coordinate system is assumed.)
  If multiple objects in a sketch match the assumed given of a tool, the tool chooses the most recently-created of the matching objects. This makes it possible to create a tool that iterates by producing an object that will be used as an assumed given for the next use of the same tool.
• Constructible givens are objects that can be matched either by themselves, or by matching their given parent points. Depending on how the tool user interacts with them, they can function as either givens (when matched by themselves) or productions (when matched by their parents). A constructible given is created by labeling it with a label that begins with constructible, and its parents are automatically included as simple givens. Every parent of a constructible given must be a point; the constructible given can be a line, segment, ray, circle, arc, or polygon.
  Constructible givens are typically matched directly rather than by their given parent points; see the section on Matching Order for More details.

Tool Object Labels

As you author a tool, you can use the label of each tool object to detrmine both the behavior and the label of that object during toolpLay.

Determine the Behavior of Given Objects

You can use the label of a given tool object to determine the behavior of that given object during toolplay. The following methods apply only to given tool objects::

• Determine the roles of the given objects: You can specify the following tool roles by beginning with the name of the desired tool role (given, constructible, or assumed). Note that tool roles apply only to given objects, not to other tool objects.
• Determine the order of in which given objects become active: Following the tool role, you can specify a match-order, which is the order in which given objects become active. For example, if the tool contains three given points and a constructible segment and you want the constructible segment to be the first active given, you can label the three given points given2, given3, given4 and label the constructible segment constructible1.

To be recognized, the tool object’s label must begin with the tool-role followed by the match-order (if any). If you also want to specify a label or any other signal (see below for Label Signals), you must insert a colon immediately after the match-order, or immediately after the tool role if there is no match-order.

Assign Labels to Tool Objects

When you create a tool, you can use the labels of the tool’s objects to control the labeling of the resulting objects in the sketch. The following methods apply to all tool objects:

• Use WSP’s default label sequences. A tool point labeled A, played repeatedly, will produce sketch point A, then B, then C, and so forth. The sequence for straight-object labels is j, k, l, ... The sequence for functions is f, g, h,... and for parameters it’s t₁, t₂, t₃,.... This is the default behavior, so you don’t need to do anything special in the tool beyond labeling your point as A, your segment as j, or your function as f.
• Determine whether the object is labeled: The sketch object will be labeled if and only if the tool object is labeled.
• Determine whether the label is shown or hidden: The resulting sketch-label visibility will match the tool-label visibility.
• Create a specific label for the object: Put quotation marks on the tool-object label to force the same label on the sketch object. A tool segment labeled "m" (including the quotation marks) creates a sketch segment labeled m each time the tool is used. Avoid quoted labels if a tool might be used repeatedly in a sketch; it’s rarely useful to produce multiple objects with identical labels.
• Specify the label format for the object: Some objects, such as transformed images, support multiple label formats. For instance, a reflected image of point >P in segment jcan be labeled using prime notation or two forms of function notation. The default is prime notation (P' in this example), or r(P) (short format), or r_j(P) (full format). See Label Formats below for more information.
• Create a custom label sequence: When a tool is designed for repeated use, you may want a labeled object to begin with a label different from the default. For instance, you might want successive points labeled x, y, and z, or you may want a parameter that’s labeled x_i, x_j, and x_k.
To create these
• PROBLEM: I was going to say you could get a custom sequence just by starting with (for instance) point x, and the sequence (x,y,z) would be tied to this tool object. but then what happens if the user creates (for instance) points P, Q, and R. Does this make 3 sequence that overlap? And the label generator will presumably still avoid duplicates, so if there’s already point Q in the sketch and you use a tool that specifies points P, Q, and R they will appear in the sketch as points P, R and S. I think there needs to be a clear, simple way of identifying a label that will produce a custom sequence. We should not willy-nilly assume that the presence of point G in a tool means that the user intends this point, when next played, to be point H. Perhaps we should specify that this behavior will result only if the object’s label ends with two periods. So then I could label the tool object as "x.." as the signal to create a custom sequence x, y, z, and get those three labels from three applications of the tool.l Similarly, point A1..would lead to A2, A3, etc. on subsequent toolplay.
• ANOTHER SCENARIO: Say I create a tool with both A.. and D.. First we get A & D, then B & E, then C & F, then G & H, I & J, etc. I guess that’s ok, and just a sign that custom sequences should be used with care.

PICK UP FROM HERE...

In the source sketch for a tool, you label objects in ways that determine how they will be used, labeled, and formatted during toolplay. Because the tool author seldom knows ahead of time what labels are already in use by the sketch into which the tool is played, tools don’t normally apply specific labels to either their givens or their productions. But you can add certain codes to the labels of tool objects to determine formatting options, visibility, and other features.

Because it serves multiple functions, the label of a tool object can have multiple elements, ordered as follows:

1. Given Role (required for given objects): This element specifies the type of a given object of a tool. Possible values are "given", "constructible", and "assumed."
2. Match Order (optional, applies to given objects only): This element specifies the order in which given objects become active during toolplay. Values are integers.
3. Colon (optional, applies to given objects only): A colon is required to separate a given object’s role (and match order if present) from any subsequent elements, and can be omitted if there are no subsequent elements.
4. Label (optional): >The label of this object in the tool’s source sketch. (This label isn’t normally used in the target sketch, where new unique labels are generated during toolplay. If your tool needs to define the label to be used in the target sketch, use the _apply_ code described below.)
5. Label Codes (optional): You can use these codes to determine the way an object’s label is formatted and displayed. Each code begins with a space to separate it from any previous label element and is surrounded by underscores. Here are the codes you can use.
   • Visibility: The _hide_ and _show_ codes determine whether the label in the target sketch will be hidden or shown. Without a visibility code, the target sketch object will display a label if the source sketch object has a label, and will not display a label if the source object is unlabeled.
   • Format: The format codes determine the formatting of transformed images. See Specifying Label Formats below for details.
   • Label Use: The _apply_ code applies this object’s source-sketch label to the constructed object in the target sketch.

Label a Given Object

1. Identify:Each given object of your tool must be identified by a label that begins with given, constructible, or assumed. There’s no need to identify the parents of a constructible given; they are automatically identified as given objects.
2. Set the Matching Order: Once the user activates a tool, each given object of the tool glows when it’s ready to be matched. The default matching order of the givens is the order in which they were created in the original sketch, but you can explicitly set the matching order by appending a number to the label. Thus parameter given1 will be matched before line constructible2, and both will normally be matched before point given3. (If for some reason you wanted a segment to be constructible but to have its given endpoints become the active givens before the segment, you could label the endpoints given1 and given2, and the segment constructible3. More typically you would just label the segment constructible and not bother to label the endpoints.)
3. If a given uses a specific label or any of the codes below, append a colon immediately after the matching order (or after the given/constructible/assumed if there is no matching order). At this point a label might show “given3:” or “constructible:”

Specify the Object Label

For an assumed given you must indicate the label of the sketch object to which it will be matched; for instance, “assumed: Center” to automatically match this assumed given to a sketch object labeled “Center.”

You might want to use a label to help you keep track of the roles of particular objects in the source sketch. If you specify the label of a given, the label must follow the colon. If you specify the label of a production, the label should start at the very beginning.

Examples: “assumed: Center”, “given3: A”, “P”

Note that only the “assumed: Center” example represents an actual label in the sketch. When the tool with point “P” as one of its productions is used in a sketch, the point it creates will be unlabeled. (But see the _apply_ code described below.

Format Object Labels

You can label any tool object in ways that affect the visibility and format of the label. Below are the codes you can use. Note that each code begins and ends with an underscore, and that one code must be separated from another by a space.

• _hide_ , _show_ : Use one or the other of these codes to force the object’s label to be hidden or shown. If the tool object has a label, the default behavior is that the resulting object will create and show a unique label. If the tool object has no label, the default behavior is that the resulting object will have no label.
• _prime_, _short_, _full_, _manual_, _auto_, _none_ :
These codes match the Label Widget radio buttons for formatting transformed objects (_prime_, _short_, _full_, and _manual_), measurements and calculations (_auto_, _manual_, and _none_), and parameters and functions (_manual_ and _none_).

Labels of Given Objects

The label of any given object starts with given or constructibleGiven optionally followed by a number defining its sort order, optionally followed by a colon (“:”) and its desired user-facing label. Thus a given object labeled given3: Center is a simple given, has a sort order of 3, and will appear to the user with the label “Center”. To provide this label without making it visible during toolplay, hide the entire label. If you hide the label given3: Center, the label will not appear during toolplay, but if the user reveals it later it will appear as “Center.”

You can specify the format to use in labeling certain objects (such as transformed objects) created by tools. To apply a specific format in the source GSP sketch, label the object this way: "nameOrigin: format", replacing format> with one of the formats listed below. (In both GSP and WSP, labels can include subscripts by enclosing the subscript in square brackets.)

• Transformed Objects:

  The first row of the table shows the formats available for labeling a transformed object in the source GSP sketch. The second row shows the same formats as they appear in the Label Widget. The third row shows an example: the label that results when a pre-image point A has been rotated about center point C by angle θ. For example, if the tool’s rotated image in the source GSP sketch is labeled "nameOrigin: namedByFullFn", the resulting image point is labeled r_C,θ(A).

  Format (GSP source)	namedByPrime	namedByShortFn	namedByFullFn	namedFromLabel
  Format (Label Widget)	Prime	Short	Full	Manual
  Label Code	_prime_	_short_	_full_	_manual_
  Resulting Label	A′	r(A)	rC,θ(A)	(next available default label)



• Measurements and Calculations:

  The first row of the table shows the formats available for labeling a measurement or calculation in the GSP source sketch, and the second row shows the formats as they appear in the Label Widget. The third and fourth rows show examples of the resulting labels that result when a tool has been used to create a measurement (the ordinate of point A) and a calculation.

  Format (GSP Source)	namedFromTemplate	(user label)	namedFromLabel	noVisibleName
  Format (Label Widget)	Auto		Manual	None
  Label Code	_auto_		_manual_	_none_
  Resulting Label (measurement)	xA = 3.00	m[1]	m1 = 3.00	3.00
  Resulting Label (calculation)	2·xA+ 5 = 11.00	m[2]	m2 = 11.00	11.00



• Parameters:

  The first row of the table shows the formats available for labeling a parameter in the GSP source sketch, and the second row shows the formats as they appear in the Label Widget. The third row shows an example: the resulting label when a tool has been used to create a parameter.

  Format (GSP Source)	(user label)	namedFromLabel	noVisibleName
  Format (Label Widget)		Manual	None
  Label Code		_manual_	_none_
  Resulting Label	t[1]	t1 = 1.50	1.50



• All Other Objects:

  All other objects not mentioned above have “manual” labels that can be created in the GSP source sketch or typed into the Label Widget.

Matching a Given Parameter

You can match a parameter to any compatible value in the sketch, where “compatible” means having the same kind of units: distance, angle, or scalar (without units). A parameter or measurement in radians can be interpreted either as an angle or as a scalar (in its sense as the ratio between arc length and diameter), so radian values are considered to be compatible with both angle values and scalar values.

Matching a parameter to “any compatible value” means that the user of the sketch can match not only another parameter, a measurement, or a calculation, but can also match any text object in the sketch that contains or refers to a compatible value. This includes both pegged text—text attached to a point—and composite text—text that includes values and/or labels of other objects in the sketch. (Composite text is sometimes referred to as “hot text.”) In such cases, the pegged text or composite text must have exactly one value-containing ancestor. It doesn’t matter whether the actual value or only the label of the value-containing ancestor appears in the pegged or composite text; in either case the given parameter will be matched to that ancestor’s value.

Order of Given Objects

Constructible Givens

Restrictions on Constructible Givens

Sequential Snapping

Per-Page Tools

You can specify which tools should appear on each page of a websketch. For instance, if your GSP document has three tool pages named WSP Tool: Point, WSP Tool: Segment, and WSP Tool: Circle, you could make the Point tool appear on all pages, make the Segment tool appear on both pages 2 and 3, and make the Circle tool appear only on page 3. To do so, create a WSP Preferences page, and enter the following captions:

• SegmentTool = 2,3
• CircleTool = 3

Because the Point tool is not listed, it will appear on all pages of the websketch.

New Parameter, Calculation, and Function Tools

You can author a tool that allows the user to create and edit a new Parameter, Calculation, or Function. If your tools has only a single such given, then when that tool is played by the user, the numberpad or calculator will automatically come up. A given calculation of 1+1 is automatically replaced by an empty calculation, and will appear in the sketch in edit mode.

Auto-Play Tools

An auto-play tool has only assumed givens, and no other givens that can be matched. When you tap such a tool, it completes its constructions and finishes without any further interaction. [Unfortunately at the current time the Exporter doesn’t support tools without simple givens, so there is a temporary work-around in place to make it possible for you to author such a tool. In desktop Sketchpad, create the auto-play tool with all its assumed given objects, and then add to your sketch a single point labeled "given: delete". This will satisfy the current exporter, and the "given: delete" point will automatically be deleted from your tool when your sketch is loaded.]

Image Icon

To identify your tool in the WSP toolbox using an image rather than the tool name, add a free picture to the sketch. If there are multiple free pictures in the sketch, the first one is used, and the others are ignored.

Tool Look

There are three skins that determine the appearance of the toolbox: classic, new, or compact. Use Author Preferences to set the desired skin, by placing a caption on the WSP Preferences page. The caption should be of the form "Tool Look = " followed by the name of one of the three skins.

• classic is the original skin, showing an icon representing the tool if the WSP Tool page contains a free picture, or the name of the tool otherwise.
• new is a skin that shows both an icon (if the WSP Tool page contains a free picture) and the name of the tool.
• compact is a skin that provides yet another look in which the tools appear as buttons 105 pixels wide with corners that are more rounded. This look is optimized for use with icons, but if there’s no icon for a tool, it’s identified by name using a 20-pixel font size. Short names, up to about 10 characters, are preferred.

Incorporating Tool Help in WSP-based Student Activities

There are two pathways to enabling Tool Help for tools in websketches that you create. Both involve using the Web Sketchpad Tool Library, because all tools in the library’s Basic collection are help-enabled.

1. Go to the Tool Library and use it to create the websketch. On some pages you may want users to manipulate or add to an initial construction that you create, and you may want to leave some pages empty so that students can create their own constructions. To create an initial construction on a page, you can use any of the tools in the Tool Library. When the initial constructions are finished, drag to the Trash any tools that should not be available to users. If you want users to have different tools available on different pages, use the check boxes in the tool list to indicate which tools will be available on each page.
2. Create your original sketch using The Geometer’s Sketchpad (GSP) for Mac or Windows. (There is no need to create "WSP Tool" pages in your sketch, unless you decide to create specialized tools not available in the Tool Library.) Use the WSP Exporter to export your sketch in .json form, and upload it into the Tool Library. Use the Tool Library to add whatever tools users will need, and use the checkboxes in the tool list to indicate which tools will be available on each page.

Once your sketch is finished in the Tool Library, download it in .json format and incorporate it into your webpage.

Examples