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|
|Sliders and buttons||x||x|
|Zoom and Shift||x||x|
|Multiple synchronized graphics||x||x|
|Easy access to variables||x|
|Suitable for long computation||x|
|Multiple instances||on 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
is enough to display a sine evaluated for angles between 0 and
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.
- 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:
- In our example, the vertical coordinate of the point being manipulated in array y is replaced by the vertical position of the mouse.
- 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.
- Several subplots can be displayed with command subplot. Commands label and title may be used to add labels.
if firstrun x = 1:10; y = rand(2,10); end
|_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|
|_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)|
switch _id case 1 y(_nb,_ix) = _y1; end
plot(x, y, 'r', 1);
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);