en fr

Disponible uniquement en anglais

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.

SQ scripts SQ files
Interactive graphicsxx
Sliders and buttonsxx
Zoom and Shiftxx
Multiple synchronized graphicsxx
Easy access to variablesx
Figure menux
Settings menux
Undo/Redox
Savex
Functionslibraries onlyx
Suitable for long computationx
Helpx
Multiple instanceson some platforms

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:
NameDescription
_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);