/***************************************************************************\
*                                                                           *
*       !MoleDraw,                                                          *
*                                                                           *
*       Molecular DTP,                                                      *
*                                                                           *
*       version 0.239D (21-May-96),                                         *
*                                                                           *
*        Simon Kilvington, 1993-96                                         *
*                                                                           *
\***************************************************************************/


   MoleDraw is an object based drawing program orientated towards producing
diagrams of chemical structures. It allows you to easily draw pictures of
molecules which can then be exported as Draw files to other applications.

   To ease the transfer of data between MoleDraw and other applications it
supports the new RISC OS global clipboard. This allows you to cut, or copy,
data from one application and paste it into another, all at the touch of a
couple of keys.


Compatibility
=============

   MoleDraw has only been tested under RISC OS 3.10. It should be compatible
with all versions of RISC OS from 3.00 onwards, but it will not work under
earlier versions.

   MoleDraw requires Acorn's DrawFile module.


Overview
========

   The basic principle behind creating drawings in MoleDraw is very much
like 'Draw'. That is, you choose an object from the toolbox, or from the
menu if you don't like toolboxes, then position it on the drawing.

   Once objects have been added to the drawing they may be selected and then
moved, rotated, grouped together, etc.

   The main difference between MoleDraw and Draw is that the objects used in
MoleDraw have been chosen to allow chemical structures to be quickly and
easily drawn. MoleDraw also knows about atoms and bonds and uses these
concepts to not only ease the production of neater drawings, but also to
allow you to build connection tables from your diagrams of chemical
structures. The connection tables can be saved as SMILES strings, these are
a popular and simple way of describing the connectivity in chemical
structures as a one dimensional string of characters. They are described in
the file '!MoleDraw.docs.SMILES'.

   Although MoleDraw knows about bonds and atoms it allows you to draw any
structure you want, however chemically unreasonable it may be. The
philosophy is "you know what you are doing" and so it does not impose any
constraints on what you can draw. Silly structures can even be exported as
silly SMILES strings, although these will not be accepted as input to the
2D->3D/3D->2D converter that will be my next project.

   MoleDraw's toolbox contains the following tools, each of which may also
be accessed from the main menu. Their use is described below.

                +-------------------+-------------------+
                | Bond              | Select            |
                +-------------------+-------------------+
                | Dashed bond       | Erase             |
                +-------------------+-------------------+
                | Wedge             | Label             |
                +-------------------+-------------------+
                | Dashed wedge      | Caption           |
                +-------------------+-------------------+
                | Thick bond        | Arrows (menu)     |
                +-------------------+-------------------+
                | Thick dashed bond | Orbitals (menu)   |
                +-------------------+-------------------+
                | Wiggly bond       | Objects (menu)    |
                +-------------------+-------------------+
                | Chain             | Reflected chain   |
                +-------------------+-------------------+
                | 3 atom ring       | 4 atom ring       |
                +-------------------+-------------------+
                | 5 atom ring       | 6 atom ring       |
                +-------------------+-------------------+
                | 7 atom ring       | 8 atom ring       |
                +-------------------+-------------------+
                | Chair             | Reflected chair   |
                +-------------------+-------------------+
                | Cyclopentadiene   | Benzene           |
                +-------------------+-------------------+

   The toolbox icons may be quite big in small screen modes, ie 12 (640x256
pixels), 27 (640x480) etc. This is because I use mode 39 (896x352) which has
a fairly large screen area. Mode 31 (800x600) is also quite nice, and you
get the hi-res icons.


Using bond and ring tools
=========================

   Firstly use the 'Style' menu to choose the colour, line width etc that
you want your new object to have. The description of the 'Style' menu below
explains exactly what is effected by the 'Line width', 'Bold width' etc.

   Once you have decided on a style choose the object type you want to add
to the drawing either from the toolbox or the 'Enter' menu. To add an object
to the drawing first click with 'select' where you want the object to
appear. The position of the object will be shown as a light blue outline
which moves as you move the mouse. Once the object is in the desired
position click again with 'select' to add it. You may click with 'adjust' at
this point instead to move the position of the initial click and start
entering the object again.

   Pressing the 'Escape' key at any point will abandon the entering process.

   From the 'Tools' menu you may select 'Fixed lengths' and/or 'Fixed
angles'. These restrict the size and orientation of the objects and allow
you to ensure that all your molecules turn out the same size. Note that
moving the mouse when entering 'Chain' objects changes the number of bonds
to be added, not the length of the bonds which is always the 'Fixed' bond
length.

   Even if 'Fixed lengths' and/or 'Fixed angles' are selected if your last
mouse click when entering a bond is over an atom the bond will end at that
atom. This applies to rings too, and so polycyclic structures can quite
easily be constructed.

   The 3, 4, 5, 6, 7 and 8 atom ring tools can be used to produce aromatic
rings, ie with a circle drawn in the middle of them. To get aromatic rings
hold down 'Shift' when you first click with 'select', or if you subsequently
click with 'adjust'. At its closest point, the circle will be one and a half
times the bond spacing away from the bonds that form the ring.

   When a new bond is aligned on top of an existing single bond it will
become a double bond, doubles will become triples, and triples will go back
to singles again. This only happens for the single bond tools. The rings,
the chains, and the chairs will not increase the bond order of existing
bonds they overlap.

   The program places an atom at the end of each bond, these can not be seen
but may later have a label added to them, or be output as a connection table
in the form of a SMILES string.


Using tools with a menu
=======================

   The 'Arrows', 'Orbitals' and 'Objects' tools each have a menu of objects
associated with them. Before you can use one of these tools you must choose
from its menu which object you want to enter. To display the tool's menu
either click with 'menu' or double click with 'select' on the toolbox icon,
or use the 'Enter' menu. Once an object is chosen from a tool's menu it will
be used each time the tool is used.

   Once an object has been associated with the tool proceed as before to add
it to the drawing, ie click with 'select' initially, move the mouse to
position the object correctly, and click with 'select' again to add it.

   As before, 'adjust' can be used to reposition the object's starting
point, and 'Escape' abandons the process.

   Note: when entering objects they are drawn as outlines to speed up the
screen update. However, when entering orbitals there may be some doubt as to
which lobe will be filled and which will be clear. If there is any doubt the
lobe closest to the mouse pointer will be the one coloured in.


Atom labels
===========

   To add a label to an atom choose the label tool from the toolbox and
click with 'select' over the appropriate atom. A dialogue box will open
allowing you to edit the atom's label.

   Atoms may be labelled with either a dot, eg to highlight the position of
an atom between two double bonds, or with some text. The top left part of
the dialogue box allows you to decide which you would prefer. If you choose
a dot the rest of the dialogue box is ignored, so just click on 'OK' to add
the dot to the drawing. The radius of the dot is about a third of the label
font size.

   If you choose to label your atom with text the other two areas of the
dialogue box need to be set up. Firstly the text itself can be entered. Two
characters have special meanings when entering the text for labels, these
are '^' which causes the next character to be superscripted, and '_' which
subscripts the next character. So typical label texts might be 'H_2N',
'COO^-', or even 'CO_2^-'. The final section of the label dialogue box deals
with the position of the text relative to the atom. 'Left', 'Right', and
'Centre' mean that the leftmost, rightmost, or central character in the
label should be placed at the atom's position. 'Above' and 'Below' mean the
label text is stacked vertically above, or below, the atom. If you delete
the text of an atom label and then click on the 'OK' button the label will
be deleted.

   While 'Label' is the selected tool the 'Style' menu can be used to alter
the font type, size and colour used to label atoms. If an atom is already
labelled and you edit it with the label dialogue box the existing font
style, size and colour will be retained. To force a label to adopted the new
settings you should first select it and then use the 'Style' menu to alter
it. Alternatively you can delete it, either with the 'Erase' tool or by
deleting its text using the label dialogue box, and then re-create it in the
new style.

   Note: only one font can be used per label. However it may sometimes be
necessary to use a mix of Greek and Roman letters in an atom label. To
overcome this problem there are two fonts available, TimesGR and
HelveticaGR, that combine both Greek and Roman characters. These were
designed by the Archimedes Club of Athens and are public domain. The
'!Chars' application comes in handy here too! If the fonts were not included
with this program they are available via anonymous ftp from HENSA,
('micros.hensa.ac.uk' - look for 'GREEKFONTS' in the index), or from me if
you do not have access to the internet.


Captions
========

   To add a caption to your drawing choose the caption tool and click with
'select' where you want the caption to start. Alternatively you may click
with 'select' within an existing caption, this will allow you to alter its
text.

   Characters typed on the keyboard will be added to the caption. As is
usual the cursor keys may be used to move about in the text. Holding down
'Ctrl' while pressing the left or right cursor key will move to the start or
the end of the text. 'Shift' and the left or right cursor key moves the
caret to the start of the previous or next word. The 'Copy' key will delete
the character in front of the caret, and 'Delete' or backspace will delete
the character behind it.

   The main menu will change into the captions menu while a caption is being
edited. This has options to allow you to change the font, the colour of the
text etc. See the menu section below for full details.

   To finish editing a caption and to add it to the drawing either choose
'Finish' from the caption menu or press 'Return'. As you may have realised
this means captions may only contain a single line of text. This should be
enough for most purposes as MoleDraw is designed for drawing diagrams, not
writing essays. However, if you feel this is a major omission please let me
know. I am a democracy so if the will of the people is for multiline
captions they will (probably) be implemented.

   Pressing 'Escape' or choosing 'Abandon' from the menu at any point will
return the caption to its original state, ie before you started editing it.

   Note: you may click with 'select' somewhere within the caption you are
currently editing, this will move the caret to the character position
closest to the mouse. If you click outside the current caption, the current
caption will be added to the drawing (as if 'Finish' had been chosen) and a
new caption will be started at the mouse position (or, if there is one, the
caption under the mouse will be edited).


Erase tool
==========

   The 'Erase' tool will delete whatever it is clicked over. Be careful,
groups count as a single object!

   The only time this does not apply is if the tool is clicked over a bond
or an atom. In this case only that bond or atom is removed, even if it is
part of a group. When an atom is deleted, all bonds to it are also deleted.


Select mode
===========

   When in select mode existing objects may be selected and subsequently
edited. To select an object click with 'select' somewhere within it, it will
be highlighted by having a red box drawn around it, and any previously
selected objects will be unselected. To add an object to the current
selection, or to remove a selected object from the selection, click on it
with 'adjust'. By double clicking with 'select' it is possible to burrow
through a stack of objects to select ones at the bottom. Finally objects may
be selected/unselected by using 'select' or 'adjust' to drag out a box
around them. In other words it works in exactly the same way Draw does.

   Once you have made a selection of one or more objects it may be edited in
a number of ways. The selection can be moved by dragging from within one of
the objects, all the selected objects will be moved by the same amount.
Rotation and resizing of the selected objects is also possible by dragging
either the top right or bottom right selection box 'ear'. Again it works in
exactly the same way Draw does. (This is the beauty of having a windowing
system with a consistent user interface, once you know how to work one
program all similar ones are easy).

   You may cancel a move, rotate, or resize action at any time while you are
dragging the mouse by pressing the Escape key.

   The selection can be acted upon with the 'Edit' menu. This allows you to,
amongst other things, group and ungroup objects, rotate and scale them by
specific amounts, and flip them horizontally and vertically. The 'Edit' menu
also gives you access to clipboard operations. See the Menus section below
for full details.

   The selection can also be altered with the 'Style' menu. This effects how
objects appear on the drawing, their colour, font styles etc. Changing a
particular item in the 'Style' menu will alter all relevant objects in the
selection, eg changing the font will effect label and caption objects in the
current selection but will not effect anything else (as they have no text in
them). See the Menus section below for a description of all the style items.

Notes:

   Holding down the 'Shift' key while clicking with 'select' over a double
bond will alter the positions of the two bonds that form it. They will cycle
between the following three cases:

            ------
           C------C      ->      C======C      ->      C------C
                                                        ------

   If one molecule is moved, pasted etc, so its atoms overlap another
molecule's atoms the overlapping atoms and bonds will be combined into
single objects. If two overlapping atoms both have labels the furthest
forward label will be kept (use the 'Edit->Front' menu option to bring an
object to the front of the drawing). For overlapping bonds the bond with the
highest bond order is kept. If both bonds have the same bond order the
furthest forward bond is kept.

   When a molecule is rotated the text that forms its atom labels will be
kept horizontal.

   Resizing an atom label will alter the size of its rubout box but the text
will stay at the same point size. If the label box is made too small some,
or all, of the text may not be displayed.

   When another tool is chosen the current selection will be unselected.


Menus
=====

   Note: the close buttons of dialogue boxes act as 'Cancel' buttons, ie
when clicked on everything you've changed is forgotten and the program
returns to exactly the state it was in before the dialogue box was opened.

!!! we need real Cancel buttons !!!

Iconbar menu

Info            leads to a dialogue box showing the program version etc.
Preferences...  choose this to open the preferences window (see later).
Paper limits    leads to a dialogue box that allows you to choose the
                default paper size and how many pages the drawing extends
                over. These will be used by all new files. The default paper
                size and number of pages is stored on disc along with the
                other preferences when they are saved.
Quit            asks for confirmation if there are unsaved files, and then
                quits the program.


Main menu

Info            as on the iconbar menu.

File
  Info          leads to a dialogue box giving information about this
                drawing. The size of the file, if it has been modified since
                it was last saved, etc.
                keyboard shortcut: ctrl F1
  Save          leads to a 'Save as' dialogue box. If any objects are
                selected then the dialogue box will contain an icon marked
                'Selection only'. Choose this and only the selection will be
                saved.
                To save a drawing that has been saved before you may just
                click on 'Save' in the 'File' menu, ie there is no need to
                open the 'Save as' dialogue box in this case.
                keyboard shortcut: F3
  Export        leads to a menu of file types that the file may be saved as.
                Each entry in the 'Export' menu leads to its own 'Save as'
                dialogue box. See later for a description of each export
                file type.
  Print...      choose this to open the printer window (see later).
                keyboard shortcut: Print
  Paper limits  leads to a dialogue box allowing you to alter the size of
                paper used by this particular drawing. Unlike the iconbar
                menu option this does not effect any other drawings except
                this one.

Edit
  Undo          returns the drawing to the state it was in before the last
                operation you did.
                keyboard shortcut: F8
  Cut           replaces the clipboard data with the current selection, then
                removes the selected objects from the drawing.
                Note: the clipboard is an application wide entity and so
                data placed on the clipboard by MoleDraw can be pasted into
                other clipboard supporting applications.
                keyboard shortcut: ctrl X
  Copy          as 'Cut' but the selection is not removed from the drawing.
                keyboard shortcut: ctrl C
  Paste         adds the contents of the clipboard to the drawing. If the
                the mouse pointer is over the drawing window the top left
                corner of the pasted objects will be at the mouse position.
                If the mouse is not over the window the pasted objects will
                be centred on the current view.
                Note: the clipboard contents could have come from another
                MoleDraw drawing, or even another application. As long as
                the other application can produce DrawFile format data.
                keyboard shortcut: ctrl V
  Delete        removes the selection from the drawing.
                keyboard shortcut: ctrl K
  Select all    selects all the objects in the drawing.
                keyboard shortcut: ctrl A
  Clear         unselects everything that is currently selected.
                keyboard shortcut: ctrl Z
  Front         moves the current selection to the top of the drawing so
                they obscure objects behind them.
                keyboard shortcut: ctrl F
  Back          moves the current selection to the bottom of the drawing so
                they are obscured by objects in front of them.
                keyboard shortcut: ctrl B
  Group         groups the current selection into a single object.
                Note: groups may be nested, ie groups of groups are allowed.
                keyboard shortcut: ctrl G
  Ungroup       ungroups selected objects that have previously been grouped.
                keyboard shortcut: ctrl U
  Scale         leads to a dialogue box that allows you to scale the
                currently selected objects in the X and Y directions.
                Negative scaling factors can be used to invert an object.
                keyboard shortcut: ctrl S
  Rotate        leads to a writeable menu entry that allows you to rotate
                the selected objects through a given angle. The angle should
                be in degrees. Positive angles specify clockwise rotations.
                Rotation of each object (groups count as a single object)
                takes place about its centre.
                keyboard shortcut: ctrl R
  Horizontal flip       these last two options flip the selected objects
  Vertical flip         either horizontally or vertically.

Style           altering options in the 'Style' menu has a different effect
                depending on whether there are any selected objects or not.
                If no objects are selected the 'Style' menu allows you to
                choose how objects you subsequently add to the drawing will
                appear. If there is a current selection then altering
                options in the 'Style' menu will also change the appearance
                of any relevant selected objects.
  Font...       when labels or captions are the selected tool choosing this
                opens a font panel window (see later). This allows you to
                choose which font, and size, you want.
  Colour        leads to a normal colour chooser dialogue box.
  Line width    the line width determines the width of bonds and other
                objects.
  Bold width    the bold width effects the width of thick bonds, the width
                of the ends of wedges, the width of wiggly bonds, and the
                size of all styles of arrow head.
                It also determines the size of the gap between the two
                arrows that form retrosynthetic and equilibrium arrows, and
                the width of the large outlined and filled arrows. However
                these will not be effected by changes in the bold width when
                applied to the current selection.
  Dash spacing  effects dashed bonds, dashed lines (in the objects menu),
                and dashed arrows.
  Arrow heads   four different styles of arrow head are available, they
                effect all arrows produced by the arrows menu.

Enter           options in the 'Enter' menu have the same effect as choosing
                the relevant tool from the toolbox.
  Bonds         leads to a menu of possible bond types.
  Rings         leads to a menu of possible ring types.
  Chains        leads to a menu allowing you to choose which direction you
                want the chain to start in.
  Label
  Caption
  Arrows        leads to the 'Arrows' menu.
  Orbitals      leads to the 'Orbitals' menu.
  Objects       leads to the 'Objects' menu.

Select          enters select mode, ie is equivalent to choosing the pointer
                icon from the toolbox.
                keyboard shortcut: F6

Tools
  Fixed lengths toggles between fixed and unrestrained bond lengths.
  Fixed angles  toggles between fixed and unrestrained angles. The 'angles'
                referred to are the orientations allowed when entering bond,
                ring, chain, and orbital objects.
  Rulers        toggles the page rulers on and off.
  Grid          clicking on this option toggles grid lock on and off. It also
                has a submenu that allows you to choose the shape of grid,
                the grid spacing, etc. Entering objects when both grid lock
                and fixed lengths/angles are enabled may be a little
                confusing. The grid is best used to align objects after they
                have been drawn.
  Toolbox       toggles the toolbox on and off.

View
  Scale view    leads to a dialogue box allowing you to alter the scale of
                the current view onto the drawing.
                keyboard shortcut: ctrl F9
  Units         leads to a submenu allowing you to change the units of
                measurement for the current drawing. This changes things
                such as the page rulers (if present) and the line width etc
                dialogue boxes in the 'Style' menu.
  Paper colour  leads to a colour chooser dialogue box that allows you to
                alter the background colour of the drawing. This only alters
                the background colour used on the screen (and in things that
                need to obscure what is below them, eg orbitals, label
                rubout boxes, etc). To get the required paper colour when
                printing you must use the right colour paper in the printer.
  Show pages    places lines on the drawing to show where the page breaks
                occur.
  Print borders toggles whether or not the print margins are shown as a grey
                border on the drawing. The width of these will depend on the
                settings for the current printer.


Captions menu

   The captions menu replaces the main menu when a caption is being added to
the drawing.

Font...         choosing this opens a font panel window that allows the font
                style and size to be changed in mid-caption.
Aspect ratio    leads to a submenu that allows you to change the ratio of
                font width to height. It is expressed in percent, so 50%
                gives characters half their normal width.
Superscript     choosing this option toggles between superscripted and
                normal text. The submenu allows you to alter the size and
                position of superscripted text.
Subscript       choosing this option toggles between subscripted and normal
                text. The submenu allows you to alter the size and position
                of subscripted text.
Underline       choosing this option toggles between underlined and normal
                text. The submenu allows you to alter the thickness and
                position of the underlining.
Colour          leads to a colour chooser dialogue box allowing you to alter
                the text colour.
Abandon         abandons the current caption, ie returns the drawing to the
                state it was in before you started editing the caption.
                keyboard shortcut: Escape
Finish          tells MoleDraw you have finished editing the caption, and
                adds it to the drawing.
                keyboard shortcut: Return


Other keyboard shortcuts
========================

   ctrl Cursor Up   - double view scale
   ctrl Cursor Down - halve view scale


Preferences
===========

   The preferences window can be brought up either from the icon bar menu,
or by clicking with 'adjust' on the icon bar. It allows you to set up the
line width, bold width, fonts etc. used as default by each new drawing.

   Most options have a fairly obvious effect. Some may need a little
explanation. The 'tolerance' defines how close the mouse pointer must be to
an existing atom for the program to assume the mouse is over that atom. This
determines whether new bonds added to the drawing will be bonded to existing
atoms, and whether atoms will be merged when dragging them. The 'chain
angle' determines the angle between bonds created with the chain tool.
Finally, the 'bond spacing' is the distance between components of multiple
bonds. It is expressed as a percentage of the bond length, so longer
multiple bonds will have components that are further apart.

   Where line widths or other distances are needed a width of 0 means draw
the thinnest line possible.

   Once you have set up your preferences you may save them by choosing the
'Permanent' icon, or use them now without saving them by choosing the
'Temporary' icon. Closing the window cancels any changes you have made since
you last chose 'Temporary' or 'Permanent'.

Notes:

   Most changes made to the preferences will not effect files currently
being edited, but will only effect files subsequently loaded or created.
Changes that will effect all files are, the fixed length and angle, the
tolerance, the chain angle and the bond spacing.

   The page size set up with the 'Paper limits' option on the icon menu will
be saved with the preferences when 'Permanent' is chosen in the preferences
window.


Printer window
==============

!!! write about me, please !!!


Font panel
==========

   This allows you to choose a font style and size. It presents you with a
list of the font families installed on your computer, and the typefaces
available for each one, in two scrollable windows within the dialogue box.
Select a family and typeface from the lists and the new font will be
previewed at the top of the dialogue box.

   To the right of the family and typeface lists is a list of standard font
sizes (in points) from which you can choose. Alternatively you can enter a
size of your own in the writeable icon at the bottom.

   Click on the 'OK' button to confirm your new selection and dispose of the
font panel window.


Loading and saving
==================

   MoleDraw saves its data as Draw files. Although these files contain extra
data that MoleDraw uses (the coordinates of atoms etc) they are arranged in
such a way that any normal DrawFile renderer will draw them exactly as they
appear in MoleDraw. Information about the format of the Draw files produced
by MoleDraw can be found in the '!MoleDraw.docs' directory.

   You will find that if you load a MoleDraw file into !Draw you will not be
able to move any of the atom labels or bonds. This is because MoleDraw uses
'tagged' Draw objects in its files. These are normal Draw objects (and so
can be rendered by Draw etc) but they have some extra data tagged on to the
end of them. !Draw does not allow you to move tagged objects because this
extra data may be somehow related to the objects coordinates (which it is,
indirectly, in MoleDraw).

   Files may be exported in various formats. 'Draw' saves the file as a
normal DrawFile except that none of the extra information normally saved by
MoleDraw is included. This reduces the size of the file, but means that if
it is loaded back into MoleDraw it is treated as just a picture, not a
collection of atoms and bonds that can be manipulated in a chemically
sensible way.

   Files may also be exported as Sprites. The Sprite will have the same
number of colours and resolution as the current screen mode. The Sprite will
be just large enough to hold all the objects. The easiest way to get a given
sized Sprite is to draw a box around the objects - in the background colour
if you don't want a border around your Sprite.

   'SMILES' files are text files containing a concise representation of the
connection table. The SMILES format is commonly used in the computational
chemistry field and is described in the file '!MoleDraw.docs.SMILES'.
MoleDraw assumes all atoms are carbon unless they are labelled with chemical
symbols. Subscripted numbers and superscripted number/charge combinations
are handled in the way you would expect. So for example a label of 'CO_2^-'
produces a charged carboxylic acid group in the resulting SMILES string.


Known problems
==============

   When you choose an item from the 'Arrows', 'Orbitals' or 'Objects' menu
the choice applies to all files, not just the one you are currently using.

   Font handles are not updated on mode changes. This means if you are
editing a caption and you change the screen mode the fonts will not look
correct until you have finished editing the caption. Also the font in the
'Info' dialogue box is not displayed correctly after changing modes, though
this is due to a bug in the RISC OS Lib C library not my code!

   Doesn't undraw drag boxes properly when !madness is running.


!!! remove these following sections !!!

#ifdef DEBUG

Bugs to fix
===========

ctrl+shift+F12 causes MoleDraw to exit but nothing else - although it does
work as expected occasionally (!?)

Doesn't redraw window properly when rescaling from eg 200% to 100% and the
window is scrolled right across to the right.

Restyling arrow heads: doesn't get it right if the arrow object has been
resized or flipped horizontally or vertically (in fact anything that changes
the aspect ratio of the arrow head) - cuz it uses the old arrow head coords
and assumes the predefined aspect ratio to calc the angle/size the restyled
one should be.


Fatal internal errors
=====================

   Some fatal errors will cause a stack backtrace to be produced, ie a list
of the procedures currently being executed. You will be warned before this
happens, by a normal error box, and given a summary of the following
instructions:

   while the error box is still on the screen,
   hold down ctrl+shift (to stop the backtrace scrolling passed too quick)
   click on 'OK' to remove the error box
   a white window will appear with nothing in it
   release shift for a very short time and the first part of the backtrace
will appear
   write down the top two or three procedure names
   release shift again to see more
   once all the backtrace has appeared press space to continue

   See if you can consistently repeat the problem, and tell me about it!

   Sometimes an error box may appear with a message that starts "debug:".
These are not (necessarily) fatal errors but are still things that I should
know about! Try to find out how to repeat them.

#endif


Release history
===============

v0.145D (23-Sep-94)

   Development version that lacked, among other things: captions; undo;
saving of 'Export' file types; printing; background colours other than
white; using 'Shift' to get aromatic rings; and the ability to alter the
attributes of objects in the current selection with the 'Style' menu.

   Only released to a select few to get some feedback about how it was
shaping up.

v0.168D (15-Dec-94)

   Development version released to Carl Cepurneek for testing. Additions:
aromatic circles; benzene and cyclopentadiene tools do not increase bond
order of existing bonds they overlap; drawings can extend over more than one
page; font list is updated each time a Font Panel is opened; various bug
fixes. New captions can be entered, but they are not added to the drawing
when you've finished - also a bug in the caption editing code means fonts
are not "lost" after being used, so the font cache tends to get full up with
useless information.

v0.169D (17-Dec-94)

   Development version that fixed the 'Font_Lose' bug and handled subscripts
and superscripts in captions better. It still doesn't add the captions to
the drawing when you've finished editing them though. Released to various
interested people on 'comp.sys.acorn' for testing.

v0.182D (15-Jan-95)

   Captions can now be added to the drawing. They become either text objects
or text areas, depending on their complexity. Sadly at the moment text areas
can not be re-edited once they have been created. Also the bounding boxes of
text area's are not always the correct size.

   Should now work on RiscPC's as all 'draw_verifyObject()' calls have been
removed. Uses Acorn's DrawFile module to render drawings now as the RISC OS
Lib one can't do text areas with colour changes properly.

   Released to the 'comp.sys.acorn' people for more testing.

v0.184D (6-Feb-95)

   Minor bug fixes. Still no re-editing of text areas.

v0.185D (12-Mar-95)

   Big gap - been busy. Pasted data is now pasted at the position of the
mouse pointer if it is over the drawing window. If not it is centred on the
current view as before. Still haven't finished the text areas stuff. I've
got lots of things planned out, they're just not coded up yet.

v0.195D (21-Apr-95)

   You can re-edit text areas at last! Now, when entering bonds, even if
fixed angles/lengths are selected if you do the last mouse click on an atom
the new bond ends at that atom. The pointer now has different shapes for
different tools. You can now export Draw files (ie without all the extra
data MoleDraw usually adds to them). When you drag the mouse to move, rotate
or resize an object any moving bonds are also drawn during the drag instead
of just the bounding boxes. When a molecule is moved, pasted etc, so its
atoms overlap another molecule the overlapping atoms/bonds are now combined
into single objects. [Still a couple of loose ends to tie up in the merging
overlapping atoms stuff].

v0.200D (18-Jun-95)

   Bug fixed in the 'Export->Draw' code. Keyboard shortcuts for scale and
rotate menu options added. Sprite objects can now be flipped horizontally
and vertically. Minor bug fixes. When dragging, the bounding boxes of
objects that contain only bonds are not drawn, just the bonds are. When
dragging molecules to move them, any atoms in the molecules automatically
'snap' to the positions of existing atoms in the drawing when they are
within the tolerance set up with the preferences. [This doesn't work for
dragging to rotate or resize yet]. All the loose ends in the merging
overlapping atoms stuff have been sorted out, except one. The groups which
merged bonds etc end up in may not always be what you might expect.

v0.222D (6-Jan-96)

   Single bonds do not get put in groups on their own now when exporting
Draw files. I've got Acorn's new C compiler so the code should be smaller
and faster than with the older one! Bug fixes in changing text objects and
merging atoms after dragging. The 'Style' menu can now be used to restyle
the current selection. Undo is implemented for most operations, exceptions
are: the erase tool; the caption tool; and using shift-click to alter double
bond positions. There is a bug lurking somewhere in the undoing stuff,
sometimes the connection table gets corrupted when you drag one molecule so
it overlaps another after you've just undone something. Basically, at the
moment be careful if you do lots of undoing.

v0.225D (4-Feb-96)

   You can undo erasing and captions now. Haven't been able to repeat the
undoing bug! But I fixed another obscure memory problem so it may have been
caused by that. Sorted out the eor plotting so now objects being placed on
the drawing are plotted in cyan even in 256 colour modes and the marks on
the rulers that show where the cursor is don't disappear in 256 colour
modes. I haven't been able to test this in 32K or 16M modes. The paper
colour can now be changed.

v0.226D (25-Feb-96)

   Undo changes to paper colour/size etc implemented. Arrows, lone pairs,
and +/- signs now effected by fixed lengths/angles. Apparently text area
objects, eg labels, don't appear in Impression Publisher. This will be the
next thing to be sorted out - when I've got some spare time!

v0.230D (24-Mar-96)

   Found and fixed the undo memory bug. Added a Draw type grid. Apparently
Impression can't handle text areas in Draw files, so the next thing to do is
to change labels to (groups of) text objects.

v0.237D (21-Apr-96)

   Sprite files can now be exported. Atom labels are now text objects,
rather than text areas. This means the bounding boxes are better and
Impression can display them. Fixed the problem with tall brackets being too
fat.

v0.239D (21-May-96)

   Bug fixes.


Notable omissions
=================

Can't export SMILES files yet.

No printing, and therefore no 'View->Print borders'. At the moment you have
to print your drawings by loading them into Draw.


ToDo list/ideas
===============

when dragging - scroll the window when the mouse ptr gets near to an edge

when entering chains - cursor says how many C atoms so far

when entering objects - highlight atoms as mouse moves over them

have some sort of user editable library of common structures and labels
which can be quickly accessed from the menu or the toolbox

style guide says pasted data should replace the current selection - do we
want to implement this?

click on the units name at the corner of the rulers to cycle through types
of units

be able to load !!!AND PASTE!!! sprite files => wimp3 paste stuff needs to
be able to handle more than one filetype

used fixed angle when doing rotation by dragging

error and label dbox open twice

sort out shift+ctrl+F12 exiting - probably same problem as error boxes etc
opening twice - ie window handler getting called twice for some reason

on fatal errors may need to change ptr shape back to normal

fatal errors - save drawings to Wimp$Scrap

put cancel buttons in dboxes and get rid of their windows close buttons.
Keep close buttons in actionless dboxes, eg proginfo etc

2D templates - check 'globals.threed' variable

see which wimp messages we are really interested in

see how big wimpslot needs to be

support interactive help application (ie !Help)

Drag 'n' drop

Be able to break bonds so they appear to be behind another, eg for bridged
rings etc

check that resizing text area objects with more than one column (test it
with about ten) works properly


Production version
==================

undefine DEBUG when compiling

set 'remove proc names' etc flags when compiling, I think 'Features' 'fah'
are all the things that need setting

!!! remove this section !!!


Acknowledgements
================

   Firstly thanks to Carl Cepurneek for lots of comments, ideas, bug reports
and useful E-mail discussions.

   Thanks to Steve Perkins for drawing the original 'rubber' sprite, (the
current ones are slightly squashed versions of it).

   Thanks also to Stewart Rubenstein who wrote the original Mac version of
'ChemDraw', of which this is a blatant copy. They say imitation is the
sincerest form of flattery. However, hopefully ChemDraw is only copyrighted,
and not patented, otherwise this program may only be available for a very
short time before I become embroiled in an expensive legal battle!

   Finally, thanks to Guttorm Vik for writing 'StrongEd'. All the source
code and most of the other text files were written using it.


Use and Copying of this program
===============================

   MoleDraw is a 'Freeware' program, ie you can freely use and copy it as
long as all of the following files are copied (unaltered) with it:

   !MoleDraw.!Choices
             !Help              (this file)
             !Run
             !RunImage
             !Sprites
             !Sprites22
             docs.DrawFiles
                  mdobjs
                  SMILES
                  SMILESegs     (a MoleDraw file!)
             Messages
             Sprites
             Sprites22
             Templates

   The '!Choices' file is updated by the program as needed, you should not
need to edit it yourself.

   If you feel you have been charged an excessive amount of money for this
free program please remember, for future reference, that you can get copies
of my programs by sending me a disc, your address, a nice letter and a stamp
in a jiffy bag.


Postamble
=========

   Any comments, suggestions, bugs or donations can be sent to:

   Simon Kilvington,
   46 Mead Road,
   Portishead,
   Bristol,
   BS20 8NY.

   or send an E-mail to 'srk@soton.ac.uk'.


---
Simon Kilvington, 8/4/96
