Sysquake Miscellaneous Functions
Cancel an operation.
In a handler, it is often useful to cancel the whole operation. Avoiding changing any variable is not enough, because it would leave a new set of variables which would make the Undo command not behave as expected. The cancel command tells Sysquake to cancel completely the operation, be it a menu handler or the sequence of mousedown, mousedrag and mouseup handlers. cancel throws an error; hence its effect will be caught if it occurs in a try block.
In the middle of a mousedrag operation, it may happen that the mouse cursor in over an invalid region, but the drag should not be canceled. cancel(false) cancels the current execution of the mousedrag or mousedragcont handler, keeping the current value of the output variables.
In a mouseover handler or idle handler, cancel(false) prevents the figures to be updated with execution of draw handlers.
if ~dialog('Do you really want to make the system unstable?') cancel; end closedLoopRoot = 2;
Check if a feature is available.
b = hasfeature(str)
hasfeature(str) returns true if Sysquake supports the feature whose name is given is string str, and false otherwise (even if the feature does not exist in any version). Currently, the following features are supported in some versions of Sysquake:
|fileio||low-level file I/O (fopen etc.)|
|lapack||Lapack-based linear algebra functions|
|xml||XML DOM functions|
Open a file embedded in the SQ file.
fd = efopen(efblockname) fd = efopen(efblockname, encoding)
efopen(efblockname) gives a file descriptor to read the contents of a block of type embeddedfile in the current SQ file. The file descriptor can be used exactly as if it was obtained with fopen for a real file in text mode, with functions like fgets, fgetl, fscanf, fread, fseek, and feof. Function fclose must be used to release the file descriptor.
efopen(efblockname,encoding) specifies one of two possible encodings for the contents of the block: 'text' for text (default value), or 'base64' for base64. Base64 is used to represent binary data as text. Each character of encoded data represents 6 bits of binary data; i.e. one needs four characters for three bytes. The six bits represent 64 different values, encoded with the characters 'A' to 'Z', 'a' to 'z', '0' to '9', '+', and '/' in this order. When the binary data have a length which is not a multiple of 3, encoded data are padded with one or two characters '=' to have a multiple of 4. The encoded data is usually split in multiple lines of about 60 characters. The decoder ignores characters not used for encoding.
With a base64 encoding, input functions have the same effect as if an nonencoded file had been opened; i.e. the encoded data are decoded on the fly.
Base64 encoding is an Internet standard described in RFC 1521.
To convert a file to base64 in order to embed it in an SQ file, you can use function base64encode as follow:
fd = fopen(getfile); while ~feof(fd) fprintf('%s\n',base64encode(char(fread(fd,45)))); end fclose(fd);
If the file is too large to let you easily copy the result from the command-line interface to the SQ file, you can store it in an intermediate file:
fd = fopen(getfile('Input')); out = fopen(putfile('Output'), 'wt'); while ~feof(fd) fprintf(out,'%s\n',base64encode(char(fread(fd,45)))); end fclose(fd);
Control the state of idle processing.
idlestate(b) b = idlestate
idlestate(b) enables the periodic execution of the idle handler if b is true, or disables it otherwise.
With an output argument, idlestate gives the current state of idle handler execution.
When a Sysquake handler executes slowly, typically for more than 1 second, Sysquake displays a hint that it is working and the user should wait. The exact appearance of the hint depends on the platform: it can be graphical or textual.
With multiple calls to progress(r), a handler can indicate to Sysquake the ratio of work completed thus far, from r=0 (start) to r=1 (end). Depending on the platform, Sysquake uses the value to display the progress hint as a progress bar or a percentage. The hint is always hidden automatically at the end of the handler execution.
progress should be called in handlers expected to take some time to execute, such as menu, import or export handlers. But it does not harm to call it in fast handlers or often, because its own execution is quick and the display update rate remains under the control of Sysquake.
function doComputation n = 1e3; for i = 1:n doComputationStep(i); progress(i / n); end
quit quits Sysquake. It has the same effect as choosing Quit or Exit in the File menu.
Create a new text window for output.
fd = textoutputopen(title) fd = textoutputopen(title, markup)
Function textoutputopen(title) creates a new text window with whose title is the string title. It returns a file descriptor which can be used with all output functions, such as fprintf. Text output is accumulated into a buffer which is displayed in the window.
With a second input argument, textoutputopen(title,markup) creates a new text window for plain text if markup is false, or text with markup if markup is true. The markup is the same as what is accepted on file descriptor 4.
The text window can be closed with fclose(fd). The contents of the buffer can be reset with clc(fd). Depending on the application and the platform, the
Create a window for text with markup and write some text:
fd = textoutputopen('Example', true); fprintf(fd, '=Example=\n'); fprintf(fd, 'This is a paragraph.\n\n'); fprintf(fd, 'Here is a list:\n* Alpha\n* Beta\n');
Get current language.
(lang, code) = sqcurrentlanguage sqcurrentlanguage(lang) sqcurrentlanguage(code)
sqcurrentlanguage retrieve the current language chosen by the user for the user interface. It returns up to two output arguments: the first one if the language and the second one is the language code, as defined with beginlanguage in the SQ file.
With a string input argument, sqcurrentlanguage changes the current language to the one specified by language name or code.
Get path of SQ file.
str = sqfilepath
sqfilepath gives the path of the current SQ file. If the path is not available (e.g. if the SQ file was not loaded from a file), sqfilepath returns an empty string.
Get the path of a data file stored in the same directory as the SQ file:
pathDir = fileparts(sqfilepath); pathDataFile = fullfile(pathDir, 'data.txt');