
QCALC
=====

This is a little spreadsheet which actually started out as a hobby project,
but turned out to be quite useful if you want to play around with Q. It lets
you run *all* Q functions, no strings attached, and you can define your own
functions in a script and use these in the spreadsheet, too. As such, it
should be useful as an educational tool, or if you simply want to play around
with the Q interpreter in a more convenient graphical and interactive
environment.

Please note that this is more a replacement frontend to the Q interpreter
rather than a full-blown spreadsheet, so some functionality you know from
other spreadsheets may still be missing or be implemented in a slightly
different way. But if you've ever worked with MS Excel or its OpenOffice and
KOffice equivalents, you should feel right at home. The only major difference
is that each cell may hold either text, a number *or* any Q value, and that
the full Q interpreter is used to evaluate your formulas.

IMPLEMENTATION NOTE: This program uses forkpty to implement the pipe to the Q
subprocess which does the actual calculations, and thus requires a Unix-like
system at present. It should be quite straightforward to replace this with
socket-based communication between the GUI and the interpreter, which would
also work on Windows, but this hasn't been done yet.

INSTALLATION
------------

Currently this script needs Qt3, but we're planning to port it to Qt4 asap.

IMPORTANT: You'll need Qt/Q 1.2 or later. Earlier Qt/Q versions will NOT WORK!

To install from the source, simply run 'sudo make install' (this installs into
/usr/local). You can specify a different installation prefix with 'sudo make
install prefix=some/path'.

Note that for QCalc to work properly, the calclib.q script needs to be on the
QPATH, therefore it is recommended that you install under the prefix where
your Q installation lives. Otherwise you will have to set your QPATH
accordingly.

USAGE
-----

Documentation can be found in the doc directory, and is also available online
with the F1 key or the corresponding options in the Help menu of the
application. Please also have a look at the spreadsheets in the examples
directory for some examples.

After installing the program, you can simply fire it up using the command
'qcalc' or 'qcalc mysheet.qcalc'. To exit the program, use the 'Quit' option
of the 'File' menu or just press Ctrl-Q; you will be warned and get a chance
to abort the operation if the current file hasn't be saved yet.

Note that QCalc saves spreadsheets in a text format which is in fact valid Q
script syntax, but uses the '.qcalc' extension by default. (The contents of
the spreadsheet are stored as comments at the beginning of the script; it goes
without saying that you shouldn't remove or alter these lines if you edit the
file with a text editor!) It is also possible to open any plain Q script,
which then becomes an empty spreadsheet with the given Q source as the user
script.

Also note that there's only one spreadsheet and one script per file in the
current implementation. But the spreadsheet can get as large as you want and
each cell may hold an arbitrarily complex Q value. The user script may import
other source files as necessary, using Q's import/include statements, so the
single script page doesn't really limit what you can do either.

TODO
----

Known bugs and limitations:

- Copying formulas (as opposed to the plain cell contents in tab-separated
  format) via the clipboard uses the special MIME type text/x-qcalc-data. This
  doesn't seem to work when transferring values across different applications;
  apparently Qt then only allows you to transfer text/plain and image data.
  Inside a single QCalc instance, transferring formulas works just fine, so
  for the time being the workaround is to copy the data you want, load the
  target file in the same QCalc instance and then paste it as usual.

Some stuff that would be nice to have in future releases:

- CSV file import and export.

- LaTeX export.

- Special cell attributes like number format, alignment, color, font and
  frames, etc. Currently you'll have to help yourself with ASCII art or with a
  'label' GUI element.


Enjoy! :)

Dec 2007
Albert Graef <Dr.Graef@t-online.de>
http://q-lang.sf.net
