#
#  QGLE - A Graphical Interface to GLE
#  Copyright (C) 2006  A. S. Budden & J. Struyf
#
#  This program is free software; you can redistribute it and/or
#  modify it under the terms of the GNU General Public License
#  as published by the Free Software Foundation; either version 2
#  of the License, or (at your option) any later version.
#
#  This program is distributed in the hope that it will be useful,
#  but WITHOUT ANY WARRANTY; without even the implied warranty of
#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#  GNU General Public License for more details.
#
#  You should have received a copy of the GNU General Public License
#  along with this program; if not, write to the Free Software
#  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
#
#  Also add information on how to contact you by electronic and paper mail.
#

Introduction
------------

The current GUI contains a preview window that can receive messages from 
GLE and display the resulting EPS file.  In addition, it can open EPS 
and GLE files directly (using Ghostscript and GLE).  It now has the 
capability to add lines, circles and arcs to the drawing (snapping to a 
grid if required) and also to add a single "amove" at the end of the GLE 
file (so that the user can add additional commands).  At some point 
there will be additional functions to add text and other functions.

When drawing lines, hit the escape key to cancel.  The pointer tool can 
be used to select lines (and the amove object) and they can then be 
deleted using the 'del' key.  Other keyboard shortcuts include:

F1 : Show this message
F3 : Toggle Object Snap
F6 : Toggle coordinate display (Cartesian, Polar, 
                                Relative Cartesian, Relative Polar,
                                Off)
F7 : Toggle grid visibility
F8 : Toggle Orthographic snap
F9 : Toggle grid snap
F10: Toggle polar snap

'-': Zoom in
'=': Zoom out

Shift: Hold this down to select multiple objects for deletion

At present, there is very little error checking, so expect regular 
crashes.  Also, if compiled in debug mode, there's a fair amount of 
debugging output sent to the console, but I'm gradually cutting this 
down as it gets more stable.  To recompile in 'release' mode, change
"CONFIG += debug" to "CONFIG += release" in the qgle.pro and recompile
everything.

Once compiled, run "qgle" to start.  This will bring up the main window
with a status bar message saying "Server Listening".

Once "gle -p" has been run, the eps should appear in the window and the
full file name in the status bar.  At the moment, the window won't
resize for different sized EPS files, but this may well change.

BUGS:

* Cannot directly open GLE files where they contain latex expressions:
  something seems to be wrong with the way GLE is called;
* Temporary files (used for rendering GLE code) are never deleted;
* Icons on the toolbar are horrible;
* Very little error checking in the code, therefore very likely to crash 
  or just do something very strange;
* I'm sure there are a lot more bugs, but I haven't found them all yet 
  and haven't written down those that I have found: answers on a 
  postcard to the usual address.

TODO:

* Fix all the bugs!
* Allow editing and moving of lines and other objects;
* Line trimming and extension;
* Allow drawing of boxes etc;
* Allow addition of "mtext";
* Add object ordering;
* Add object properties e.g. fill;
* Extend polar snap to work from other snap points;
* Editing of objects in existing gle files;
* Add exporters: PDF etc;
* Add printing;
* Make lines into polylines and allow object conversion;
* Add custom objects built from subroutines;
* Allow addition of arbitrary gle code at a given position?


Compiling the GUI
-----------------

Nothing as fancy as autoconf here, the compilation is managed by QT's
qmake.  The program is designed for QT4 (which is fairly different to
QT3), so make sure you have the right version operable (they can
coexist) by running "qmake --version".  If it says "Using QT version
4.1.1" then you're up to date, if it's 4.something-else, it should still
work.

On Arch Linux, the QT4 package lives in /opt/qt4 whereas QT3 lives in
/opt/qt.  There is a script called qt-config (not to be confused with
qtconfig), which switches the development environment between the two.

Once you're sure you're running the right version, do the following:

tar -xzf qgle.tar.gz
cd qgle
qmake
make
./qgle

To compile in debug mode in Windows (selectable using the config option 
in qgle.pro), you MUST have compiled the debug libraries (using the 
option on the "Start" menu).  If you haven't done this, you'll probably 
get some random unexplained crashes.


Code Description
----------------

The code is organised as follows:

readme.txt            : This file.
doxyfile              : A configuration file for doxygen, ignore at will.

mainwindow.h          : The class definition for the main window.
mainwindow.cpp        : The class implementation for the main window.
                        Contains most of the signal-slot connections and
                        the handlers for the menus etc.  Also handles 
                        opening of files and rendering of GLE/EPS files.  
                        A large amount of the functionality of the 
                        program is contained in this file.

gledrawing.h          : The GLEDrawingArea class definition.
gledrawing.cpp        : The GLEDrawingArea class implementation.  This
                        class controls the (white) drawing area in the
                        middle of the screen.  This resizes to fit a 
                        loaded image and allows the drawing of lines and 
                        other objects.

drawingobject.h       : GLEDrawingObject class definition.
drawingobject.cpp     : GLEDrawingObject class implementation.  This 
                        class is the parent class of all drawing objects 
                        in QGLE (except the final "amove").  Also 
                        contains static functions for coordinate 
                        transforms.

line.h                : GLELine class definition.
line.cpp              : GLELine class implementation.  This class (a 
                        child of GLEDrawingObject) implements lines 
                        (amove/aline).

arc.h                 : GLEArc class definition.
arc.cpp               : GLEArc class implementation.  This class (a 
                        child of GLEDrawingObject) implements circular
                        arcs.

circle.h              : GLECircle class definition.
circle.cpp            : GLECircle class implementation.  This class (a 
                        child of GLEDrawingObject) implements circles.

grid.h                : Grid class definition.
grid.cpp              : Grid class implementation.  Contains the 
                        location of all grid points and calculates the 
                        nearest grid point to a given position.

fileinfo.h            : File info class definition.
fileinfo.cpp          : File info class implementation.  Contains a 
                        wrapper around a GLE file, with the GLE 
                        filename, the EPS filename, the GLE code and the 
                        rendered image(s).

gsapi/                : Contains the GS header files, used by QGS.

main.cpp              : A very simple main().

qgle_definitions.h    : Program-wide definitions, currently just the port
                        number.

qgle.pro              : The QT project file.  Mainly standardised stuff,
                        includes a configuration that prevents qDebug from
                        outputting anything in release mode.

qgs.h                 : Class definition for libqgs (GSInterpreterLib).
qgs.cpp               : The libqgs class file.  This has been ported from
                        the original code to better support EPS files and
                        to compile as QT4.  Thanks to Jan for getting 
                        this working in Windows.

qgslibloader.cpp      : Part of Jan's work on libqgs.

serverthread.h        : Definition for GLEServerThread.
serverthread.cpp      : The implementation for GLEServerThread.  This
                        thread includes a simple tcp server listening on
                        (by default) port 6667.  When connections are
                        received, it (crudely) parses the data and tries to
                        generate an EPS.  This is then passed to the 
                        main window for further processing.

settings.h            : Definition for settings handler.
settings.cpp          : Implementation of readAll and writeAll functions
                        for settings handler.

settings_dialogue.h   : Definition for Settings Dialogue Box.
settings_dialogue.cpp : Implementation of settings dialogue box.

about.h               : Definition for about box.
about.cpp             : Implementation of the about box.

qgle.qrc              : Qt Resource File.  Contains links to images used 
                        on the application toolbar and to this readme file.
images/               : Contains the images used on the application 
                        toolbar.
qgle.rc               : Windows Resource File.  Contains the application 
                        icon.


Al <abudden@NOSPAMgataki.co.uk>

# vim:tw=72:fo+=w2:et
