Tutorial for SQ Scripts

This chapter shows you how to develop a new SQ script for Sysquake. SQ scripts are the simplest way to make interactive graphics you can manipulate with the mouse for new problems. Basically, they are made from the commands you would type in the command window to create static graphics, with small changes to support interactive manipulation.

In the remaining of this chapter, we will develop an SQ script which displays the quadratic function a*x^2+b*x+c and its tangent at a point the user can manipulate. In the next chapter, we will write an equivalent SQ file, which will be more complicated but support undo/redo and allow us to add menus.

Displaying a Plot

In this section, we will write what is necessary to display in the same graphics the quadratic function, a vertical line which defines a value for x0, and the straight line which is tangent to the quadratic function at x0.

An SQ script is written as a text file using any text editor. If you prefer a word processor, make sure that you save the SQ script as raw text, or ASCII, and not as styled text. Sysquake handles end of lines in a sensible fashion; do not worry about the different conventions between Mac OS, Unix, Windows and other operating systems. For cross-platform compatibility, restrict yourself to the ASCII character set, and avoid two-bytes characters like Unicode and Japanese kanji (depending on the platform, bytes are interpreted as the native encoding, such as Latin-1 or Shift-JIS, or UTF-8). Once you have written and saved a file you want to test, simply open it in Sysquake. Make sure that the Command window or panel is visible, so that you can see error messages.

We can now begin to write the SQ script.

Step 1: Display the quadratic function

Type the following commands in the Command window or panel:

a = 1;
b = 2;
c = 4;
x = -10:0.1:10;
plot(x, a*x.^2+b*x+c);

The assignments set variables a, b and c to the coefficients of the quadratic function ax^2+bx+c, and variable x to an array of values for which the function is evaluated. Command plot displays the function.

Step 2: Calculate the tangent line

Let dx+ey=f be the tangent line at x0. Let us calculate d, e and f:

x0 = 1;
d = 2*a*x0+b;
e = -1;
f = (2*a*x0+b)*x0-(a*x0^2+b*x0+c);

Step 3: Display the tangent line

To display the tangent line, we use command line. Note that the quadratic function is not erased.

line([d,e], f);

Step 4: Write an SQ script

Now that we know how to display our graphics, we can store the commands in an SQ script. We group at the beginning the statements which initialize the variables we might want to manipulate interactively, for reasons which will be explained in the next step.

a = 1;
b = 2;
c = 4;
x0 = 1;

x = -10:0.1:10;
plot(x, a*x.^2+b*x+c);

d = 2*a*x0+b;
e = -1;
f = (2*a*x0+b)*x0-(a*x0^2+b*x0+c);

line([d,e], f);

Save this in a file named "tut_scf.sq" and open it in Sysquake. The graphics will be displayed automatically. Note that you can zoom and shift it interactively, something you could not do when you created the graphics from the command line.

Adding Interactivity

Step 5: Initialize variables only once

Sysquake evaluates the SQ script each time it has to update the graphics. However, there is no need to assign initial values to the variables. While it does not matter much now, it will become problematic when we add interactive manipulation of x0. Let us use function firstrun, which tells whether the script is executed for the first time, to make the initialization conditional:

if firstrun
  a = 1;
  b = 2;
  c = 4;
  x0 = 1;
end

...

Step 6: Add a vertical line at x0

To manipulate the tangency point, we add a vertical line at x0. We draw it in red, and add an identifier (the last argument) to tell Sysquake to display a hand when the cursor is near the line.

line([1,0], x0, 'r', 1);

Step 7: Change x0 when the user manipulates the line

Now comes the interesting part: interactivity. When the user clicks the figure, Sysquake evaluates the SQ script continuously until the mouse button is released. Functions are available to know which object the mouse is over and where the mouse is. In our case, we will use _id, which gives the identifier of the manipulated object (i.e. 1 for the vertical line), and _x1, which gives the horizontal position of the mouse in the coordinates of the graphics. We use a switch block to change x0 only when the user manipulates the vertical line, and we change x0 before we use it to calculate the tangent line.

The complete SQ script is now

if firstrun
  a = 1;
  b = 2;
  c = 4;
  x0 = 1;
end

switch _id
  case 1
    x0 = _x1;
end

x = -10:0.1:10;
plot(x, a*x.^2+b*x+c);

d = 2*a*x0+b;
e = -1;
f = (2*a*x0+b)*x0-(a*x0^2+b*x0+c);

line([d,e], f);

line([1,0], x0, 'r', 1);

Click the red line and drag it to the right: the tangent line will follow.