Avery 4

docs/drag.md

@@ -0,0 +1,167 @@
+---
+layout: documentation
+title: Drag
+---
+
+Drag is a property that can be applied to points, lines, and curves that allows the user to move these objects in a certain direction by dragging the object with their cursor. Drag may follow many directional patterns, as will be shown below. 
+
+There are three basic components of drag that must be defined for drag to work: 
+* `directions`: this determines how the cursor appears for dragging. The `x` direction displays horizontal arrows, the `y` direction displays vertical arrows, and the `xy` direction displays arrows going both horizontally and vertically. 
+* `param`: this describes which parameter will change when the user drags the object. This means that at least one parameter must be defined in the program for drag to act on. 
+* `expression`: this explains how the parameter will change when the object is dragged by the user in the form of an equation. The equation may be in terms of the following variables: 
+    * `x` and `y`
+    *`drag.x` and `drag.y`, which describe the position of the mouse as it is dragged. 
+    * `drag.dx` and `drag.dy`, which describe the amount that the `x` and `y` coordinate have changed from their original position as the mouse is dragged. 
+    * `params.param`, where `param` is the parameter being changed by the drag behavior. 
+
+Let us look at an example of a simple drag expression, a point that can be moved up and down while maintaining the same x-coordinate. Notice that the increments by which the y-coordinate changes depend on the `round` value of the parameter `y`. 
+
+
+<div width="500" height="425" class="codePreview">
+
+params:
+- name: y
+  value: 3
+  min: 0
+  max: 10
+  round: 0.5
+
+layout:
+  OneGraph:
+    graph:
+      objects:
+      - Point:
+         coordinates:
+         - 5
+         - params.y
+         drag:
+         - directions: y
+           param: y
+           expression: drag.y
+         label:
+            text: "`y = ${params.y}`" 
+
+</div>
+
+
+Some drag functions are more complicated. For example, see the following drag command for pivoting the slope of a line around the point (4,5). We will use the parameter `m` to represent the slope of the line. The expression for the drag is  `(drag.y-5)/(drag.x-4)` because the slope is represented by rise over run. The 'rise' of the line is drag.y, the new position of y, minus its anchor point with a y-coordinate of 5. The same logic applies to the run. As you can see, the point itself does not change position since the line will always go through the point (4,5) because we are changing the slope parameter `m`, not the location of the line.  
+
+<div width="500" height="425" class="codePreview">
+
+params:
+- name: m
+  value: 1
+  min: -10
+  max: 10
+  round: 0.01
+
+layout:
+  OneGraph:
+    graph:
+      objects:
+      - Line:
+          color: colors.blue
+          point: [4,5]
+          slope: params.m
+          drag:
+          - directions: xy
+            param: m
+            expression: "(drag.y-5)/(drag.x-4)"
+      - Point:
+          coordinates: [4,5]
+
+</div>
+
+You can attribute multiple drag commands to a single object, such as a point. See how two different drag commands could be applied to our point example from above, now with drag ability in the x-direction: 
+
+<div width="500" height="425" class="codePreview">
+
+params:
+- name: y
+  value: 3
+  min: 0
+  max: 10
+  round: 0.01
+- name: x
+  value: 5
+  min: 2
+  max: 8
+  round: 0.01
+
+layout:
+  OneGraph:
+    graph:
+      objects:
+      - Point:
+         coordinates:
+         - params.x
+         - params.y
+         drag:
+         - directions: y
+           param: y
+           expression: drag.y
+         - directions: x
+           param: x
+           expression: drag.x
+         label: 
+           text: "`(${params.x.toFixed(2)}, ${params.y.toFixed(2)})`"
+
+</div>
+
+One might also want to drag in a curved direction, such as along a sinusoidal path. (The sine curve is shown here for reference, but has no influence on the point or its drag path). 
+
+<div width="500" height="425" class="codePreview">
+
+params:
+- {name: x, value: 0, min: -10, max: 10, round: 0.01}
+calcs:
+  m: "(2*(sin(params.x)))"
+layout:
+  OneGraph:
+    graph:
+      xAxis: { min: -10, max: 10}
+      yAxis: { min: -10, max: 10}
+      objects:
+      - Curve:
+          univariateFunction:
+            fn: (2*sin(x))
+      - Point:
+          coordinates:
+          - params.x
+          - calcs.m
+          drag:
+          - directions: x
+            param: x
+            expression: params.x + drag.dx
+
+</div>
+
+It is important to note the difference between `drag.x` and `drag.dx` and when each variable should be used. `drag.x` is the placement of the cursor as it drags an object. `drag.dx` is the _difference_ between the original parameter value and the new location of the cursor. So, for example, if a point is at (2,2) and is dragged to (4,2), `drag.x` is 4 and `drag.dx` is 2. This also means that `drag.x` = `params.x + drag.dx` if x is a parameter. 
+
+Notice that we can recreate the above example by substituting `drag.x` for `params.x + drag.dx`: 
+
+<div width="500" height="425" class="codePreview">
+
+params:
+- {name: x, value: 0, min: -10, max: 10, round: 0.01}
+calcs:
+  m: "(2*(sin(params.x)))"
+layout:
+  OneGraph:
+    graph:
+      xAxis: { min: -10, max: 10}
+      yAxis: { min: -10, max: 10}
+      objects:
+      - Curve:
+          univariateFunction:
+            fn: (2*sin(x))
+      - Point:
+          coordinates:
+          - params.x
+          - calcs.m
+          drag:
+          - directions: x
+            param: x
+            expression: drag.x
+
+</div>

docs/index.md

@@ -36,3 +36,4 @@ Graph objects:
 * [point](point.html)
 * [line](line.html)
 * [curve](curve.html)
+* [drag](drag.html)

docs/line.md

@@ -159,16 +159,10 @@ layout:
 
 </div>
 
-Now, let's see how we can make a line interactive, such that it can be dragged in a number of ways. The components of the `drag` command are as follows:
-* `directions`: the direction of the dragging may be in the x direction, the y direction, or in both the x and y direction (notated `xy` as below).
-* `param`: this is the parameter you will be changing by dragging the line. In the example below, we are changing the intercepts, so `param` is `"intercepts"`.
-* `expression`: the expression describes how the `param` will change based on the amount of dragging done. See below for a concrete example. 
+Now, let's see how we can make a line interactive, such that it can be dragged in a number of ways. Look at the `drag` section of the KGJS documentation site for more background on `drag`. 
 
 First, let's see how to drag a line defined by intercepts. We want to drag the line so that it is always parallel to its starting position; in other words, the x- and y-intercepts will always be equal to each other. 
 
-* The direction of dragging can be in the x- or y-direction, so `directions` is `xy`. 
-* We are given the parameter `intercepts`, and that is what we want to change. So `param` is `intercepts`. 
-* `expression` is a bit trickier to come up with. Notice that our line is of the equation _y = intercept - x_. We could also write this as _intercept = x + y_. Thus, the change in the intercept is the sum of the change in x and y. We write this as `drag.x + drag.y`, where drag is the amount that the cursor drags the line. 
 
 <div width="500" height="425" class="codePreview">