3.1. Basic Operations

The following functions allow you to retrieve information about the spreadsheet cell currently being worked on, and provide feedback about ongoing operations in the QCalc status line.

public index, row, column;

These functions are used inside formulas to access the row and column indices of the cell currently being computed. The index function returns both indices as a pair (I,J) where I and J are the zero-based row and column indices, respectively. Thus A1 will be returned as (0,0), A2 as (1,0), B1 as (0,1), etc. The row and column functions return only the row and column number, respectively.

public cellindex X, cellstr KEY, cellname KEY;

These functions can be used to convert between numeric cell indices like (0,0) and symbolic ones, either in string form ("A1") or as a quoted symbol ('A1). The cellindex function converts from a string or a quoted symbol to the numeric index of the form (I,J), whereas cellstr and cellname convert a numeric index back to a string or a quoted symbol, respectively. In the string and quoted symbol form, the $ symbol is permitted as well. Note that constructs like '(A$4) aren't really symbols in Q, but applications of the built-in $ operator, so they have to be surrounded with parentheses, as indicated. Also note that, when converting from a numeric index back to its symbolic form, the $ indicators are lost since they aren't included in the numeric representation.

The most useful routine among these probably is the cellindex function which can be used with a quoted cell symbol to embed symbolic cell names into formulas, where they are adjusted automatically when copied or filled (this conversion is already built into setval et al, see Section 3.2, so you do not have to use cellindex explicitly for these).

public message S;

This function sends a status message. The message will be shown in the QCalc status line. This can be used to provide some feedback during longer computations.

3.2. Changing Cell Values

The following functions are provided to change spreadsheet cells programmatically. They also work when executed asynchronously, i.e., from a Q thread executing in the background.

public setval KEY X;

This operation changes a cell value. It also returns that value, so that it can be applied to several cells in sequence. The given cell index KEY can be a pair of numbers as returned by the index function, or it may be specified in any of the symbolic formats supported by the cellindex routine (see Section 3.1). The X parameter may be any Q expression. If the given cell is an ordinary cell (no GUI element), then the current cell value is overwritten, so you should make sure that you do not have important data there. For GUI elements (see Section 3.3), the value of the element is changed accordingly, instead of overwriting the cell. In both cases, after changing the cell value QCalc will update its display and trigger updates in dependent cells as usual. Note, however, that the triggered changes will not take effect immediately, rather they are processed by QCalc when the current computation is finished.

public clearval KEY X;

This function works like setval, but clears the cell before setting the new value. This is useful if you want to overwrite a cell already populated with a GUI element.

public matrix KEY Xs, rowvect KEY Xs, colvect KEY Xs;

These are convenience functions implemented in terms of setval to store a list in a matrix or a row or column vector of table cells. They return the given list value. For the matrix function, Xs must be a list of lists which are all of the same size; the component lists become the rows of the matrix. The rowvect and colvect routines create matrices with just one row or column for a given list of values, respectively. In any case the matrix or vector is inserted into the table starting at the given index KEY (given in any of the formats supported by setval). NOTE: For updating a large number of cells, these operations work much faster than calling setval individually on each cell.

3.3. Basic GUI Elements

QCalc provides a fairly comprehensive set of functions which allow you to populate spreadsheet cells with various useful GUI elements:

public label ARGS, pixmap ARGS, checkbox ARGS, combobox ARGS, comboedit ARGS, spinbox ARGS, hslider ARGS, vslider ARGS, pushbutton ARGS, togglebutton ARGS;

The currently supported widget types are text labels, pixmaps, checkboxes, comboboxes (both non-editable and editable), spinboxes, horizontal and vertical sliders, push buttons and toggle buttons. The argument tuple ARGS depends on the specific kind of widget, as detailed below.

NOTE: These functions will not work if they are run asynchronously (i.e., in a secondary Q thread of the user script). They must be executed, either directly or indirectly, from a formula in a spreadsheet cell.

The following GUI elements are used to display formatted text and pixmaps in a cell:

• label S or label (S,A), where S is the text (a string) to be shown, and A (optionally) denotes the alignment of the text within the cell. The text is actually a Qt "rich text" element, which may contain a limited set of html tags as described on the QStyleSheet page in the Qt manual. Hence this element allows you to have formatted text in a cell, as well as embedded images.

  The alignment is specified as a string of at most two characters specifying the horizontal and/or vertical alignment, respectively. The known horizontal alignments are "a" ("auto", which may be either "left" or "right" depending on the current locale), "c" (center), "l" (left) and "r" (right), the vertical alignments are "c" (center), "t" (top) and "b" (bottom). A singleton "c" denotes both horizontal and vertical alignment. The horizontal alignment defaults to "a", the vertical alignment to "c".

• pixmap S or pixmap (S,A,B), where S is the name of a pixmap file to be shown, A denotes the alignment (specified in the same fashion as with labels, see above), and B is a numeric value indicating the desired rendering of the pixmap. The possible values for the B parameter are 1 ("scaled", i.e., the pixmap is scaled to fill all the available space in the cell), 2 ("animated", which can be used to animate a pixmap in mng or gif format consisting of multiple images), and 0 (no scaling or animation, which is also the default). Both the A and B parameters are optional.

  Note that label elements can also have embedded pixmaps (employing the <img> tag) and thus offer pretty much the same functionality, minus the animation feature. On the other hand, labels are much more versatile in that you can combine text and images and that they also give you more options for the placement and scaling of images. Dedicated pixmap elements are most useful for showing animated mng and gif images.

Here is a screenshot showing the label and pixmap elements in a spreadsheet:

Text label and pixmap elements are normally used for display purposes only, but the corresponding cells do have a value which can be queried in other formulas, which is the text of the element or the name of the pixmap as a string, respectively. The S, A and B parameters can also be computed values, and in addition the text or filename can be changed with setval and friends, to update the cell contents dynamically, as described in further detail below.

The remaining GUI elements are typically used for value input in various forms:

• checkbox S or checkbox (S,INIT), where S is the label (a string) to be shown, and INIT (optionally) is the initial value (true or false, default is false).

  The value of a checkbox is the current status of the checkbox, a Q boolean: true if checked, false otherwise.

• pushbutton S or pushbutton (S,ICON), where S is the text of the button and ICON is the filename of a pixmap to be shown on the button. Both arguments are strings.

  The value of a push button is true as long as the button is pressed and false otherwise.

• togglebutton S, togglebutton (S,ICON) or togglebutton (S,ICON,INIT): Analogous to push buttons, but toggle buttons are switched on and off by clicking them, and have an optional INIT argument which indicates the initial state (true or false, the default is false).

  The value of a toggle button is true if it is currently on and false otherwise. (Note that a toggle button changes its state after being clicked, whereas a push button changes its state when it is pressed or released. Also note that a toggle button provides essentially the same functionality as a checkbox, using a different visual appearance.)

• combobox L or combobox (L,INIT), where L denotes the list of items (strings) to choose, and INIT (optionally) is the initial item.

  The value of a combobox is the currently selected item (a string).

• comboedit L or comboedit (L,INIT): This works like combobox, except that the combobox is editable, i.e., the user can enter new items which become part of the combobox.

• spinbox (MIN,MAX,STEP,INIT,SPECIAL,PREF,SUFF), where MIN and MAX are the minimum and maximum value, STEP is the stepsize, INIT the initial value, SPECIAL a special string used to display the minimum value (commonly used for defaults) and PREF and SUFF are strings used as prefixes and suffixes in the value display (commonly used for currency symbols and units), respectively. See the QSpinBox page in the Qt manual for details. All arguments except MIN and MAX are optional. The numeric arguments MIN, MAX, STEP and INIT may be integers or floating point values; other Q Real values are coerced to Float if possible.

  The value of a spinbox is the numeric value (any prefixes and suffixes are stripped from the value). If a SPECIAL value has been set, the corresponding string is returned for the minimum value of the spinbox.

• hslider (MIN,MAX,STEP,INIT), where MIN and MAX are the minimum and maximum value, STEP is the page stepsize and INIT the initial value (which is "clamped" to the given bounds). This creates a horizontal slider. See the QSlider page in the Qt manual for details. All arguments must be integer. The STEP and INIT parameters are optional.

  The value of a slider is the numeric value of the current slider position, an integer between MIN and MAX.

• vslider (MIN,MAX,STEP,INIT): Like hslider, but creates a vertical slider instead.

By placing a formula with a call to any of the widget functions into a cell, the cell becomes populated with the GUI element and the initial value of the GUI element becomes the new cell value. You can then change the value of the GUI element through GUI interactions, triggering reevaluations of dependent cells as if you typed the corresponding value directly into the cell.

The following screenshot shows some of these GUI elements in action:

The parameters of all GUI elements can be computed values which may also depend on other cell values (including other GUI elements). In this case the GUI element will be updated automatically whenever any of the requisite cells changes. In particular, you can also use GUI elements to display values from other cells by specifying the corresponding cell as the INIT parameter of the widget, or you can define "buddies" which always change values in concert, like a slider and an associated spinbox.

Moreover, the values of all GUI elements except the push button (which is a read-only element) can also be set with setval (see Section 3.2). This is useful, in particular, if the GUI element displays some value which is updated asynchronously.

You can find examples for all types of widgets in the guiexamples.qcalc spreadsheet included in the QCalc distribution.

3.4. Advanced GUI Elements

QCalc also provides a number of advanced GUI elements to deal with custom actions to be executed in a spreadsheet. Currently supported are action buttons, task buttons and task windows. We will describe each of these in turn.

public special actionbutton ~ARGS X;

The action button is a special push button with a slightly different visual appearance, which has an associated Q expression (special argument) to be evaluated whenever the button is clicked. The ARGS parameter has the same format as for toggle buttons (the INIT parameter specifies the initial value of the button, 0 by default). The result returned by the action expression (which can be any Q value) becomes the value of the button when it is clicked.

public special taskbutton ~ARGS X;

The task button works in a similar fashion, but instead of a direct action it has an associated background task (a Q thread) to be executed, and the button is operated as a toggle button which enables the user to "start" and "stop" the task. The ARGS parameter is the same as for togglebutton, without the ICON parameter (instead, the icon on the button is set and animated automatically in response to the current activation status of the thread). The special X parameter is the Q expression to be evaluated by the task.

Inside the background task, the index, row and column functions work as usual and provide you with the cell index of the task. (Note that these values are in fact only available in the original background task started by the taskbutton function; if your task in turn creates other threads which need to access these values, you have to pass them on to the secondary threads.)

public task_input;

The task_input function equips you with a Q semaphore queue used to communicate values to the executing task in response to GUI actions inside QCalc. Usually these are either true or false, and are sent when the button state changes (true = button is switched on, i.e. the task was "started" by the user; false = button is off, the task was "stopped" or "paused"). The background task can respond to these by taking some appropriate action, e.g., pause operation (or terminate altogether) if the false value is sent, or resume operation (if still active) when true is sent. Note that it is completely up to the task how it actually responds to these messages, if at all. However, it is a good idea to have the task at least empty the semaphore in regular time intervals to prevent the semaphore from being flooded with useless messages. In any case the semaphore queue will initially contain just the "startup" message (true if the task is initially started, false otherwise) when the tread is kicked off.

The task_input semaphore may also yield a quoted taskbutton call of the form '(taskbutton (S,INIT) X) to indicate that the task button itself was updated while the task is still running. This happens when a triggered update of the button is caused by some requisite cells of the task button formula changing values. In such a case, rather than reexecuting the taskbutton function and restarting the task from scratch, the taskbutton expression with the new parameters is sent via the semaphore. Again, it is completely up to the task how it handles such a message; it may completely ignore it, or it may just evaluate the (unquoted) taskbutton call to replace itself with the new task (to support this, the taskbutton function, unlike the other GUI elements, may also be executed asynchronously). Alternatively, the task may also extract the needed data from the quoted taskbutton call and update its own internal state accordingly. To help with this, the following task_params special form is provided, which, when applied to a quoted expression of the form '(taskbutton (S,INIT) (F X1 ... Xn)), where F X1 ... Xn is the new task expression, returns the parameter tuple (S,INIT,X1,...,Xn):

public special task_params X;

At any time, the background task can also send values back to the hosting QCalc process, using the setval function (see Section 3.2) with index as the KEY argument. For instance, you can invoke setval index false to indicate that processing has finished and the task is stopped (this is also done automatically when the thread terminates). Currently, the recognized values to be sent back are false (the task is stopped), true (the task has been started, maybe in response to an asynchronous event), and arbitrary string values (which change the text label shown on the task button). QCalc will update the button in response to these messages and also change the cell value of the task button accordingly, which may trigger updates in other, dependent cells, see the description of the setval function for further details.

Note that, no matter what the purported "started/stopped" status of the button is, the user can always check whether the task associated with the button is currently up and running by taking a look at the arrow symbol shown on the button. If the task is currently executing (even if it hasn't been "started" by pushing down the button yet), the arrow symbol will be "lit" in green, otherwise it will be greyed out. Also note that in the latter case, if the thread has exited when the user starts it by pressing the button, the task will be restarted automatically and will initially be fed with the message true to indicate that it should now go ahead with its business.

Examples for the use of action and task buttons can be found in the guiexamples.qcalc spreadsheet included in the QCalc distribution. The screenshot below shows these elements in action.

public special taskwindow X;

The task window works pretty much like a task button, minus the toggle button functionality. Instead, it provides an empty parent window inside the task's cell which can be operated directly by the task in the inferior Q process. The id of the parent window is available inside the task with the task_winid function:

public task_winid;

Moreover, the index, row, column and task_input functions work in the same fashion as with task buttons. Messages of the form (W,H), where W and H are integers denoting the width and height of the task window, are delivered via task_input at initialization time and whenever the size of the parent window changes, and quoted taskwindow calls are sent when the task window is to be updated due to changes in requisite cells while its task is still up and running.

The initial value of the task window cell is the id of the parent window. It is up to the task to change this value using setval when appropriate. It is also up to the task to draw the contents of the window, using either some external program or Q's own GUI and graphics operations. In the simplest case, you can invoke taskwindow with a trivial task (e.g., taskwindow ()) and use the supplied window id to do the actual drawing elsewhere (e.g., using a task button), or you can provide an expression which takes care of drawing the contents of the cell in the window task itself. An example for the use of task windows can be found in the mplayer.qcalc spreadsheet included in the QCalc distribution; see the screenshot below.

3.5. Gnuplot Support

The following convenience function is provided to set up a task window running gnuplot.

public gnuplot CMD DATA;

The gnuplot function allows you to embed graphical plots of your data in a spreadsheet. Gnuplot is a very comprehensive plotting software with which you can produce most common kinds of 2D and 3D diagrams quite easily. NOTE: Currently this feature only works under X11 and it also requires a fairly recent gnuplot version which supports the 'x11-external' option (at the time of this writing, this is only available with the CVS version of gnuplot as of Dec 4 2007 or later). Also note that by default, the gnuplot function assumes that your installed gnuplot program is named gnuplot. If necessary, you can set the GNUPLOT string variable to a different name for the executable.

The CMD parameter of gnuplot is a string containing the gnuplot command used to produce the plot, and DATA is the data to be plotted, usually a range of cell values. DATA can also be () if no additional data is required, or a tuple of lists if multiple datasets are to be plotted. Each dataset must either be a list of integer or floating point values, or a list of lists of such values, which will be translated to inline data in ASCII format as described in Section 61 of the gnuplot manual. Each element of the dataset becomes one line in the ASCII format. Blank lines (which are required by some plotting commands) can be produced using an empty list inside your dataset. You then use '-' to specify each dataset inside the gnuplot command as usual. Alternatively, you can also specify the data yourself inside the gnuplot command string, employing any of gnuplot's supported data formats, and use () as the DATA argument.

You can use pretty much any gnuplot command in the command string; multiple gnuplot commands are separated with a semicolon or a newline character. However, your command shouldn't specify any output terminal or file (as set with the set term and set output commands) since these will be set up by QCalc when rendering the plot for the display or a printout. Also note that plots in different cells are each produced with their own gnuplot instance, so all required setup information (axes, titles, plot styles etc.) must be included in each gnuplot command; there is no sharing of such information between different cells.

See the plot.qcalc spreadsheet included in the QCalc distribution for an example. Here is a screenshot showing gnuplot in action:

Note that the plots are really full instances of gnuplot running inside the table cells, which can be operated with the mouse as usual. For instance it is possible to rotate the 3D plot shown on the right by just dragging around the mouse in the cell.