Sysquake Pro – Table of Contents

Sysquake – Table of Contents

Sysquake for LaTeX – Table of Contents

SQ Script Reference

There are two ways to program interactive graphics for Sysquake: SQ scripts and SQ files. Both are text files based on LME, Sysquake's language. For small programs, SQ scripts are simpler than SQ files, because they do not require the declarations of variables, figures and functions; but they have limitations which make them less suitable for large applications. They should be used only for interactive graphics when no other form of user interface is necessary. The table below summaries the differences.

Structure of an SQ script

An SQ script is a sequence of LME commands and expressions, very similar to what could be typed in the command-line interface. The single command

plot(sin(0:0.1:2*pi));

is enough to display a sine evaluated for angles between 0 and 2*pi and let the user change the axis limits with the Zoom, Zoom-X, and Shift interactive commands. When the user clicks in the figure window, Sysquake interprets the mouse action and executes the whole script again. The script may check whether a graphical element was manipulated (clicked or dragged with the mouse) and react accordingly.

The typical structure of an SQ script which supports the interactive manipulation of graphical element(s) is described below. Code samples show a typical implementation for manipulating the vertical position of points; but of course, many variants are possible.

Variable initialization

Graphics depend on the value of one or more variables. This dependence enables interaction. But before any interaction occurs, the variables must be assigned initial values. Since the whole script is executed each time the user clicks with the mouse in the graphics or when the window is resized, the variable initialization must be performed only once, the first time the SQ script is run, which can be determined with function firstrun.

if firstrun
  x = 1:10;
  y = rand(2,10);
end

Interaction handling

The script checks if is called as the result of the manipulation of a graphical element. Graphical elements which can be manipulated are usually associated with an identifier (or ID), an arbitrary positive integer given in the command used to draw the element. When the user manipulates this element, the SQ script can retrieve its ID with function _id. When the click occurs far away from any graphical element with an ID, _id returns the empty array []. Typically, _id is used in a switch construct. Other functions give more information about the click, such as its coordinates:

Name	Description
_z	initial position of the mouse as a complex number
_x	initial horizontal position of the mouse
_y	initial vertical position of the mouse
_z0	initial position of the clicked element as a complex number
_x0	initial horizontal position of the clicked element
_y0	initial vertical position of the clicked element
_p0	initial position of the clicked element as a 2D or 3D vector
_z1	current position of the mouse as a complex number
_x1	current horizontal position of the mouse
_y1	current vertical position of the mouse
_p1	current position of the mouse as a 2D or 3D vector
_str1	current string parameter
_kx	factor the horizontal position is multiplied by (_x1/_x)
_ky	factor the horizontal position is multiplied by (_y1/_y)
_kz	complex factor the position is multiplied by in the complex plane (_z1/_z)
_q	additional data specific to the plot
_m	true if the modifier key (Shift key) is held down
_id	ID of the manipulated object
_nb	number of the manipulated trace (1-based)
_ix	index of the manipulated point (1-based)

In our example, the vertical coordinate of the point being manipulated in array y is replaced by the vertical position of the mouse.

switch _id
  case 1
    y(_nb,_ix) = _y1;
end

Computation

The SQ script can call any of the functions and commands of LME to compute the data required for drawing the graphics.

Graphics display

All graphics commands of Sysquake are available, such as plot, line, text, and image. The SQ script should not call clf to clear the figure window; Sysquake will take care of this.

Our example just displays in red the lines of matrix y with the plot command, and it gives them an ID of 1.

plot(x, y, 'r', 1);

Several subplots can be displayed with command subplot. Commands label and title may be used to add labels.

Here is the complete program, which is probably not very useful but shows the basic elements of an SQ script.

if firstrun
  x = 1:10;
  y = rand(2,10);
end

switch _id
  case 1
    y(_nb,_ix) = _y1;
end

plot(x, y, 'r', 1);