Add a vector tool to the graph tool.

This was requested by @somiaj in our last developer meeting after I told
him that I already had this encoded. I have had it as a custom tool for
a long time now.

The usage of the new tool is documented in the parserGraphTool.pl
macro.

The "vector" graph object derives from the "line" graph object, and the
"VectorTool" tool derives from the "LineTool" tool.  That saves some
code redundancy.

Note that there will be some minor conflicts with #1191 that will need
to be resolved.

Author: drgrice1

htdocs/js/GraphTool/graphtool.scss

@@ -235,6 +235,10 @@
 			&.gt-sine-wave-tool {
 				background-image: url('images/SineWaveTool.svg');
 			}
+
+			&.gt-vector-tool {
+				background-image: url('images/Vector.svg');
+			}
 		}
 	}
 

htdocs/js/GraphTool/images/Vector.svg

@@ -0,0 +1,96 @@
+/* global graphTool, JXG */
+
+(() => {
+	if (graphTool && graphTool.vectorTool) return;
+
+	graphTool.vectorTool = {
+		Vector: {
+			parent: 'line',
+
+			postInit(_gt, point1, point2, _solid) {
+				this.baseObj.setAttribute({ straightFirst: false, straightLast: false });
+				this.baseObj.setArrow(false, { type: 1, size: 4 });
+			},
+
+			stringify(gt) {
+				return [
+					this.baseObj.getAttribute('dash') === 0 ? 'solid' : 'dashed',
+					...this.definingPts.map(
+						(point) => `(${gt.snapRound(point.X(), gt.snapSizeX)},${gt.snapRound(point.Y(), gt.snapSizeY)})`
+					)
+				].join(',');
+			},
+
+			restore(gt, string) {
+				let pointData = gt.pointRegexp.exec(string);
+				const points = [];
+				while (pointData) {
+					points.push(pointData.slice(1, 3));
+					pointData = gt.pointRegexp.exec(string);
+				}
+				if (points.length < 2) return false;
+				const point1 = gt.createPoint(parseFloat(points[0][0]), parseFloat(points[0][1]));
+				const point2 = gt.createPoint(parseFloat(points[1][0]), parseFloat(points[1][1]), point1);
+				return new gt.graphObjectTypes.vector(point1, point2, /solid/.test(string));
+			}
+		},
+
+		VectorTool: {
+			iconName: 'vector',
+			tooltip: 'Vector Tool: Graph a vector.',
+			parent: 'LineTool',
+
+			initialize(gt) {
+				this.phase1 = (coords) => {
+					gt.toolTypes.LineTool.prototype.phase1.call(this, coords);
+					this.helpText = 'Plot the terminal point of the vector.';
+					gt.updateHelp();
+				};
+
+				this.phase2 = (coords) => {
+					if (!gt.boardHasPoint(coords[1], coords[2])) return;
+
+					// If the current coordinates are on top of the first,
+					// then use the highlight point coordinates instead.
+					if (
+						Math.abs(this.point1.X() - gt.snapRound(coords[1], gt.snapSizeX)) < JXG.Math.eps &&
+						Math.abs(this.point1.Y() - gt.snapRound(coords[2], gt.snapSizeY)) < JXG.Math.eps
+					)
+						coords = this.hlObjs.hl_point.coords.usrCoords;
+
+					gt.board.off('up');
+
+					const point1 = this.point1;
+					delete this.point1;
+
+					point1.setAttribute(gt.definingPointAttributes);
+
+					point1.on('down', () => gt.onPointDown(point1));
+					point1.on('up', () => gt.onPointUp(point1));
+
+					const point2 = gt.createPoint(coords[1], coords[2], point1);
+					gt.selectedObj = new gt.graphObjectTypes.vector(point1, point2, gt.drawSolid);
+					gt.selectedObj.focusPoint = point2;
+					gt.graphedObjs.push(gt.selectedObj);
+
+					this.finish();
+				};
+			},
+
+			updateHighlights(gt, e) {
+				const handled = gt.toolTypes.LineTool.prototype.updateHighlights.call(this, e);
+				this.hlObjs.hl_line?.setAttribute({
+					straightFirst: false,
+					straightLast: false,
+					lastArrow: { type: 1, size: 6 }
+				});
+				return handled;
+			},
+
+			activate(gt) {
+				this.helpText = 'Plot the initial point and then the terminal point of the vector.';
+				gt.updateHelp();
+			}
+		}
+	};
+})();

htdocs/js/GraphTool/vector.js

@@ -53,11 +53,11 @@ =head1 DESCRIPTION
 
 =head1 GRAPH OBJECTS
 
-There are nine types of graph objects that the students can graph. Points, lines, circles,
-parabolas, quadratics, cubics, intervals, sine waves, and fills (or shading of a region). The
-syntax for each of these objects to pass to the GraphTool constructor is summarized as follows.
-Each object must be enclosed in braces. The first element in the braces must be the name of the
-object. The following elements in the braces depend on the type of element.
+There are several types of graph objects that the students can graph. Points, lines, circles,
+parabolas, quadratics, cubics, intervals, sine waves, vectors, and fills (or shading of a
+region). The syntax for each of these objects to pass to the GraphTool constructor is summarized
+as follows.  Each object must be enclosed in braces. The first element in the braces must be the
+name of the object. The following elements in the braces depend on the type of element.
 
 For points the name "point" must be followed by the coordinates. For example:
 
@@ -119,6 +119,12 @@ =head1 GRAPH OBJECTS
 
 represents the function C<f(x) = 5 sin((2 pi / 3)(x - (-4))) + 2>.
 
+For vectors the name "vector" must be followed by the word "solid" or "dashed" to indicate if
+the vector is expected to be drawn solid or dashed.  That is followed by the initial point and
+the terminal point. For example:
+
+    "{vector,solid,(0,0),(3,4)}"
+
 The student answers that are returned by the JavaScript will be a list of the list objects
 discussed above and will be parsed by WeBWorK and passed to the checker as such.  The default
 checker is designed to grade the graph based on appearance.  This means that if a student graphs
@@ -298,8 +304,8 @@ =head1 OPTIONS
 The order the tools are listed here will also be the order the tools are presented in the graph
 tool button box.  In addition to the tools listed in the default options above, there is a
 "PointTool", three point "QuadraticTool", four point "CubicTool", "IntervalTool",
-"IncludeExcludePointTool", and "SineWaveTool".  Note that the case of the tool names must match
-what is shown.
+"IncludeExcludePointTool", "SineWaveTool", and "VectorTool".  Note that the case of the tool
+names must match what is shown.
 
 =item staticObjects (Default: C<< staticObjects => [] >>)
 
@@ -439,6 +445,7 @@ sub _parserGraphTool_init {
 	ADD_JS_FILE('js/GraphTool/cubictool.js',                     0, { defer => undef });
 	ADD_JS_FILE('js/GraphTool/intervaltools.js',                 0, { defer => undef });
 	ADD_JS_FILE('js/GraphTool/sinewavetool.js',                  0, { defer => undef });
+	ADD_JS_FILE('js/GraphTool/vector.js',                        0, { defer => undef });
 
 	return;
 }
@@ -1149,6 +1156,77 @@ sub addTools {
 				}
 			);
 		}
+	},
+	vector => {
+		js   => 'graphTool.vectorTool.Vector',
+		tikz => {
+			code => sub {
+				my $gt = shift;
+
+				my ($p1x, $p1y) = @{ $_->{data}[2]{data} };
+				my ($p2x, $p2y) = @{ $_->{data}[3]{data} };
+
+				if ($p1x == $p2x) {
+					# Vertical vector
+					return (
+						"\\draw[thick, blue, line width = 2.5pt, $_->{data}[1], *->] ($p1x, $p1y) -- ($p2x, $p2y);\n",
+						[
+							"($p1x,$gt->{bBox}[3]) -- ($p1x,$gt->{bBox}[1])"
+								. "-- ($gt->{bBox}[2],$gt->{bBox}[1]) -- ($gt->{bBox}[2],$gt->{bBox}[3]) -- cycle",
+							sub { return $_[0] - $p1x; }
+						]
+					);
+				} else {
+					# Non-vertical vector
+					my $m = ($p2y - $p1y) / ($p2x - $p1x);
+					my $y = sub { return $m * ($_[0] - $p1x) + $p1y; };
+					return (
+						"\\draw[thick, blue, line width = 2.5pt, $_->{data}[1], *->] ($p1x, $p1y) -- ($p2x, $p2y);\n",
+						[
+							"($gt->{bBox}[0],"
+								. &$y($gt->{bBox}[0]) . ') -- '
+								. "($gt->{bBox}[2],"
+								. &$y($gt->{bBox}[2]) . ')'
+								. "-- ($gt->{bBox}[2],$gt->{bBox}[1]) -- ($gt->{bBox}[0],$gt->{bBox}[1]) -- cycle",
+							sub { return $_[1] - &$y($_[0]); }
+						]
+					);
+				}
+			}
+		},
+		cmp => sub {
+			my ($vector) = @_;
+
+			my $solid_dashed   = $vector->{data}[1];
+			my $initial_point  = $vector->{data}[2];
+			my $terminal_point = $vector->{data}[3];
+
+			# These are the coefficients a, b, and c in ax + by + c = 0.
+			my @stdform = (
+				$vector->{data}[2]{data}[1] - $vector->{data}[3]{data}[1],
+				$vector->{data}[3]{data}[0] - $vector->{data}[2]{data}[0],
+				$vector->{data}[2]{data}[0] * $vector->{data}[3]{data}[1] -
+					$vector->{data}[3]{data}[0] * $vector->{data}[2]{data}[1]
+			);
+
+			my $vectorPointCmp = sub {
+				my $point = shift;
+				my ($x, $y) = $point->value;
+				return $stdform[0] * $x + $stdform[1] * $y + $stdform[2] <=> 0;
+			};
+
+			return (
+				$vectorPointCmp,
+				sub {
+					my ($other, $fuzzy) = @_;
+					return
+						$other->{data}[0] eq 'vector'
+						&& ($fuzzy || $other->{data}[1] eq $solid_dashed)
+						&& $initial_point == $other->{data}[2]
+						&& $terminal_point == $other->{data}[3];
+				}
+			);
+		}
 	}
 );
 
@@ -1163,6 +1241,8 @@ sub addTools {
 	IntervalTool => 'graphTool.intervalTool.IntervalTool',
 	# A sine wave tool.
 	SineWaveTool => 'graphTool.sineWaveTool.SineWaveTool',
+	# A vector tool.
+	VectorTool => 'graphTool.vectorTool.VectorTool',
 	# Include/Exclude point tool.
 	IncludeExcludePointTool => 'graphTool.includeExcludePointTool.IncludeExcludePointTool',
 );