[q-lang-cvs] qcalc calclib.q,1.34,1.35

[Albert G. <ag...@us...>]

Update of /cvsroot/q-lang/qcalc
In directory sc8-pr-cvs16.sourceforge.net:/tmp/cvs-serv32260

Modified Files:
	calclib.q 
Log Message:
comment changes

Index: calclib.q
===================================================================
RCS file: /cvsroot/q-lang/qcalc/calclib.q,v
retrieving revision 1.34
retrieving revision 1.35
diff -C2 -d -r1.34 -r1.35
*** calclib.q	16 Nov 2007 12:45:03 -0000	1.34
--- calclib.q	17 Nov 2007 07:19:55 -0000	1.35
***************
*** 3,7 ****
  
  /* This module provides some useful support functions for use in QCalc
!    spreadsheets. You only need to import this if you want to use any of the
     operations of this module in your spreadsheet script.
  
--- 3,7 ----
  
  /* This module provides some useful support functions for use in QCalc
!    spreadsheets. You need to import this if you want to use any of the
     operations of this module in your spreadsheet script.
  
***************
*** 9,40 ****
     therefore it is recommended that you install QCalc under the prefix where
     your Q installation lives. Otherwise you will have to set your QPATH
!    accordingly. */
  
! /* 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 index, row, column;
  
  /* The following 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 constructions 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 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, so you do not have to use cellindex
!    explicitly for these). */
  
  public cellindex X, cellstr KEY, cellname KEY;
--- 9,24 ----
     therefore it is recommended that you install QCalc under the prefix where
     your Q installation lives. Otherwise you will have to set your QPATH
!    accordingly.
  
!    Please also refer the QCalc manual for a closer description of the
!    functions provided by this module. */
! 
! /* Access the row and column indices of the cell currently being computed. */
  
  public index, row, column;
  
  /* The following functions can be used to convert between numeric cell indices
!    and symbolic ones, either in string form ("A1") or as a quoted symbol
!    ('A1). */
  
  public cellindex X, cellstr KEY, cellname KEY;
***************
*** 45,253 ****
  public message S;
  
! /* Definition of GUI elements in table cells. Currently supported are
!    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:
! 
!    - 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 Bool:
!      true if checked, false otherwise.
! 
!    - pushbutton S or pushbutton (S,ICON), where S is the text of the button
!      and ICON is the name of a pixmap file. 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 call to any of the widget functions into a cell, the cell
!    becomes populated with the corresponding GUI element. You can then change
!    the value of the GUI element, triggering reevaluations of dependent cells
!    as if you typed the corresponding value directly into the cell.
  
!    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 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 below). 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. */
  
  public checkbox ARGS, combobox ARGS, comboedit ARGS, spinbox ARGS,
    hslider ARGS, vslider ARGS, pushbutton ARGS, togglebutton ARGS;
  
! /* 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 in the inferior Q process 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 actionbutton ~ARGS X;
  
! /* The task button is a special toggle button with a slightly different visual
!    appearance and an associated background task (Q thread) to be executed in
!    the inferior Q process. 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 task_input, task_index, task_row and
!    task_column functions are available to provide the input semaphore and the
!    cell index of the task, respectively. (Note that the index, row and column
!    functions don't work in background tasks, they can only be used inside
!    formulas, so you have to use task_index, task_row and task_column instead.
!    Also note that these values are 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.)
! 
!    The task_input semaphore is 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 are 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, we provide the task_params special form which, when applied to the
!    quoted expression '(taskbutton (S,INIT) (F X1 ... Xn)), where F X1 ... Xn
!    is the new task expression, returns the parameter tuple (S,INIT,X1,...,Xn).
! 
!    At any time, the background task can also send values back to the hosting
!    QCalc process, using the setval function (see below) with task_index as the
!    KEY argument. For instance, you can do a 'setval task_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 below for further details.
! 
!    Note that, no matter what the purported "start/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 the button down 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. */
  
  public special taskbutton ~ARGS X, task_params X;
  public task_input, task_index, task_row, task_column;
  
- /* Set a cell value (and return that value). The given cell index KEY can
-    either be in the numeric format as returned by the index function or in any
-    of the symbolic formats supported by the cellindex routine (see above), and
-    X 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, 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 setval KEY X;
- 
- /* Convert a list to a matrix or row/column vector of table cells, and 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 are convenience functions to
-    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). */
- 
- public matrix KEY Xs, rowvect KEY Xs, colvect KEY Xs;
- 
  /* Implementation. *********************************************************/
  
--- 29,70 ----
  public message S;
  
! /* Set a cell value (and return that value). The given cell index KEY can
!    either be in the numeric format as returned by the index function or in any
!    of the symbolic formats supported by the cellindex routine (see above), and
!    X may be any Q expression. */
  
! public setval KEY X;
  
! /* Convenience functions to convert a list to a matrix or row/column vector of
!    table cells, and return the given list value. */
  
! public matrix KEY Xs, rowvect KEY Xs, colvect KEY Xs;
  
! /* Definition of GUI elements in table cells. Currently supported are
!    checkboxes, comboboxes (both non-editable and editable), spinboxes,
!    horizontal and vertical sliders, push buttons and toggle buttons. You can
!    find examples for all of these in the guiexamples.qcalc spreadsheet
!    included in the QCalc distribution. */
  
  public checkbox ARGS, combobox ARGS, comboedit ARGS, spinbox ARGS,
    hslider ARGS, vslider ARGS, pushbutton ARGS, togglebutton ARGS;
  
! /* The action button is a special push button which has an associated Q
!    expression (special argument) to be evaluated in the inferior Q process
!    whenever the button is clicked. */
  
  public special actionbutton ~ARGS X;
  
! /* Likewise, the task button is a special toggle button with an associated
!    background task (a Q thread) to be executed in the inferior Q process.
!    Inside the background task, the task_input function provides a Q semaphore
!    queue used to communicate values to the executing task in response to GUI
!    actions inside QCalc, and the task_params function can be used to extract
!    arguments from a quoted taskbutton call (which is sent to the task when the
!    button gets updated). */
  
  public special taskbutton ~ARGS X, task_params X;
  public task_input, task_index, task_row, task_column;
  
  /* Implementation. *********************************************************/