ChartDraw
=========

RISC OS software by Chris Johnson
Version 3.52


++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Introduction
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

What does ChartDraw do?
-----------------------

ChartDraw is a means of producing bar charts, line graphs and pie
charts. The charts can be saved as drawfiles for transfer to other
presentation applications, or can be printed directly. 

Installation
------------

For a new installation, simply drag and drop the ChartDraw application
into the directory of your choice.

If you have a previous copy of ChartDraw you have two choices.

* Move the old version of ChartDraw somewhere safe and replace it with
  the new version

* Simply copy the new version over the old version

Using ChartDraw
---------------

ChartDraw is run in the usual way by double clicking on its icon. It
will install on the icon bar.

The iconbar menu
----------------

The iconbar icon menu offers the following options.

Info-this leads to the standard information window, which also
contains a web button, allowing a quick way of accessing the download
site.

Help...-will launch the documentation (this file) in the default
browser.

New-will open a new data input window, assuming the limit to open
windows has not been reached (currently four input windows). The same
action can be achieved by simply clicking with SELECT (the left mouse
button) on the ChartDraw iconbar icon.

If the control key is held down when selecting from the menu, then a
small dialogue will be opened instead. The same action can be achieved
by simply clicking with ADJUST (the right mouse button) on the
ChartDraw iconbar icon. This allows you to set the starting size of
the data input window.

See Data input for more details on data input.

Choices...-will open the application choices dialogue, A full
description of the features available is given in the Choices page.

Quit-will remove ChartDraw from the iconbar and terminate the
program. If there is any unsaved data then a warning will be issued,
and the data can be saved or discarded as appropriate.

Screenshots
-----------

All the screen shots in these pages were obtained using Snapper, a
versatile screen capture application.

Snapper is available from
http://www.chris-johnson.org.uk/software/snap.html


++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Choices
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

The choices... dialogue
-----------------------

The choices dialogue has a number of sections, accessed via the Tabs
at the top of the window, and a set of action buttons at the bottom of
the window.

The actions available are:

Set
~~~
This will store the new settings, which will be used for all future
operations. Note that e.g. charts already displayed may not be
changed, since the local settings for each chart display will override
the choices settings.

Save
~~~~
This will store the new settings, as in Set above, and will also save
the settings to disc, so they will be used when ChartDraw is run in
the future.

Cancel
~~~~~~
Close the dialogue and ignore any changes made since it was opened.

Reload
~~~~~~
Restore the settings to those pertaining when they were last saved.

Font tab
--------

This tab allows a number of font details to be set.

For the data input window, you can change the font face, using the
popup menu button to the right of the font name, and the text size (in
pt), using the bump icons.

For the chart display, the font face used for the text on the chart
can be chosen from the font menu, accessible from the popup button to
the right of the font name. It is also possible to set the size of the
text (in pt) for the chart title, subtitles, and chart labels.

If data input or chart windows are showing when any of these options
are changed, the change will be reflected in all the open windows
immediately.

Chart tab
---------

This section contains general settings for the various chart displays,
applying to more than one type.

Default size
~~~~~~~~~~~~
This determines the size of the window used to display a chart.
Current sizes available are

640480
800600
1024768
12801024
A4 landscape
A4 portrait

Chart line widths
~~~~~~~~~~~~~~~~~
This group of options allows the setting of the default widths of
lines on the chart. The widths of the chart axis lines, data lines and
grid lines can be set (in pt) independently, using the appropriate
bump icons.

Use dashed line grid
~~~~~~~~~~~~~~~~~~~~
This determines whether the grid lines on the chart are drawn as a
solid line or as a dashed line.

Use thin lines on vdu
~~~~~~~~~~~~~~~~~~~~~
Thin lines, as understood by the draw module are not supported
directly, since the use of such lines can cause problems with e.g.
high resolution printers, when the 1 pixel wide line effectively
becomes invisible.

When using line widths of a small fraction of a pt, the VDU display
can sometimes look a little uneven, particularly with lines at an
angle to the horizontal/vertical. In some cases, lines can completely
disappear. This is where the option Use thin lines on vdu comes in. If
this is selected, then the screen display will use 1 pixel wide lines
for all the lines on the chart, but when saving draw files and
printing will revert to the actual line widths as set in this
dialogue. If this is not set, then ChartDraw will make the assumption
that lines of less than about 0.80 pt should be displayed on screen as
'thin' lines, and thicker lines will be displayed at their configured
thickness. (Why 0.8 pt? There are 72 pt to the inch, and the vdu
display is nominally 90 px to the inch. Thus 1 px is nominally 0.8
pt).

Long axis-labels display
~~~~~~~~~~~~~~~~~~~~~~~~
This group of options controls what ChartDraw does when it thinks axis
label text is too long to fit easily on the chart. There are three
options.

* Offset alternate labels in a vertical direction
* Slant the text up from the left
* Slant the text down to the right

In addition, if one of the slant options has been chosen, the angle of
the slant can be set at 30, 45, or 60 to the horizontal.

| Note that all of the above settings can be changed for individual
| charts once they are being displayed (see the chart display options
| section for a fuller description and example images). Changes made
| while one or more chart windows are showing will not affect these
| windows. Remember, the chart options are inherited by a data set when
| that data set is first created or loaded, thus these changes will only
| affect new data sets.



Bars/pies
---------

Bar chart vertical
~~~~~~~~~~~~~~~~~~
When this is ticked, then the bars on a bar chart will be shown in a
vertical format. If not, the bars will be plotted horizontally. The
axes will change accordingly.

Use shadows
~~~~~~~~~~~
When this is ticked, shadows will be added to bar and pie charts.

Black outlines on bars and pies
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When this is ticked, each component of a bar or pie chart will have a
black outline placed around its edge.

See the chart display options section for a fuller description and
example images


Line chart
----------

Always include origin in line chart
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When this is ticked, line charts will always be plotted from y = 0,
whatever the range of values in the data. If not ticked, then the axis
range will be chosen to cover the range of values, without necessarily
including the y = 0 axis.

Include symbols on line charts
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If this is selected, then a symbol (e.g. square or circle) will be
placed at each data point, as well as a line joining each point. If
not selected, then the symbol will be omitted.

Use colour for data lines
~~~~~~~~~~~~~~~~~~~~~~~~~
If this is selected, then the lines joining each data point will be
plotted in colour. If not selected, then the lines will be black.
There is currently no user option to change the colours used.

Symbol size
~~~~~~~~~~~
If plotting a line chart, each set of data points is shown as symbols
(e.g. square or circle). The size of the symbols can be set (in os
units) using the bump icons. For normal square pixel modes there are 2
os units to 1 pixel.

See the chart display options section for a fuller description and
example images



Printing
--------

Print format
~~~~~~~~~~~~
ChartDraw assumes that the printer uses A4 paper. Print format
controls how ChartDraw arranges the print out. You are offered three
options, accessed via the popup menu button.

A4 landscape
The printed chart will be formatted always to A4 landscape, whatever
the format of the screen display.

A4 portrait
The printed chart will be formatted always to A4 portrait, whatever
the format of the screen display.

Auto
With this setting, ChartDraw will attempt to print the chart in the
format of the actual screen display, printing the chart in landscape
or portrait mode as appropriate, and scaling down to fit the A4 size
if necessary. Smaller sizes (e.g. 640  480) will not be scaled up.

Show printer margins on chart display
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Most printers are not able to print to the edge of the paper. When the
screen display is set to A4 portrait or landscape, ChartDraw will
attempt to take account of the printer margins, and will not use the
whole of the A4 sized display. If a printer driver is active,
ChartDraw will read the configured printer margins from the printer
driver. If there is no driver active, default values will be used
until !Printers is loaded.

This option, when selected, will show the printer margins on the
display in a mid grey colour.

Note that the printer margins are reread whenever the active printer
is changed, so the chart margins will immediately reflect these
changes.



++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Data input
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


Clicking with SELECT on the iconbar icon, or on the New option in the
iconbar menu, will open a new data input window. ChartDraw can have
several of these windows active at any one time.

The window as opened will have a column for the data labels and one
column for the data. Clicking the mouse in an appropriate cell will
set the caret ready for text input. A chart title can be entered, as
can column headings. Extra columns can be added at any time by placing
the caret in a column heading and pressing Control-Shift-Tab. A
maximum of four columns in addition to the column of labels is
allowed. Tab will move from one cell to the next. Return will do the
same, but in addition, when in the rightmost cell, a new row will be
added when Return is pressed. The result of entering data may be as
shown below.

Clicking with ADJUST on the iconbar icon will open a small dialogue to
set the starting number of rows and columns.

For general editing of the data most of the expected special
keypresses for navigation, etc., are available. To clear a cell, use
Ctrl-U. To delete a complete row, use Ctrl-Shift-Delete. To insert a
new blank row, use Ctrl-Shift-Insert. The full set of keypresses are
described below. Options for inserting or deleting columns are
available from the input window menu).


Input window menu
-----------------

The menu attached to the data input window is shown to the right.

Add new column
~~~~~~~~~~~~~~
This option mimics the Ctrl-Shift-Tab keypress in a column header
field, and will add a new blank column at the right. If the maximum
allowed number of columns has been reached, then the option will be
shaded and not selectable.

Insert column
~~~~~~~~~~~~~
This allows the insertion of a new blank column. Follow the arrow
right to choose before which current column the new column is to be
inserted. The list of options will be shaded/unshaded depending on how
many columns there are already. If the maximum allowed number of
columns has been reached, then the option will be shaded.

Delete column
~~~~~~~~~~~~~
This allows an existing column to be completely deleted. Follow the
arrow right to select the target column. You cannot delete a single
remaining column.

Stacked bars
~~~~~~~~~~~~
This will open a chart window, in which the data is shown in stacked
bar chart format. See the chart window page for a full description.

Grouped bars
~~~~~~~~~~~~
Selecting this will open a chart window, in which all the data is
shown in grouped bar chart format. Alternatively, following the arrow
right allows you to select from a submenu just one of the columns to
be plotted. See the chart window page for a full description.

Line graphs
~~~~~~~~~~~
Selecting this will open a chart window, in which all the data is
shown in simple line chart format. Alternatively, following the arrow
right allows you to select from a submenu just one of the columns to
be plotted. See the chart window page for a full description.

Stacked lines
~~~~~~~~~~~~~
This will open a chart window, in which the data is shown in stacked
line chart format. See the chart window page for a full description.

Pie charts
~~~~~~~~~~
Selecting this will open a chart window, in which all the data is
shown in pie chart format. Alternatively, following the arrow right
allows you to select from a submenu just one of the columns to be
plotted. See the chart window page for a full description.

Save as
~~~~~~~
This leads, via a submenu offering the save either in chartdraw or CSV
format, to a standard 'save as' dialogue box. Drag the icon to a filer
window, or a suitable application, or enter the path manually to
complete the save.

Once a chartdraw data file has been saved, then double clicking on it
in a filer window will reload it in to ChartDraw. If the application
has been seen by the filer, or been filer_booted, then ChartDraw will
be launched if not already running. The saved data file can also be
reloaded into ChartDraw by dragging its file icon from a filer window
to the iconbar icon.



Keyboard shortcuts and special keys
-----------------------------------

Many of the standard key actions are available in the input window.

Left arrow
	Move caret left by one character within the current field.

Shift left arrow
	Move caret to left of data in current cell, unless already at
	left, when caret moves to previous cell in row.

Control left arrow or Home
	Move caret to end of data in leftmost cell of current row.

Right arrow
	Move caret right by one character within the current field.

Shift right arrow
	Move caret to right of data in current cell, unless already at
	right, when caret moves to next cell in row.

Control right arrow or End
	Move caret to end of data in rightmost cell of current row.

Down arrow
	Move caret down one row.

Up arrow
	Move caret up one row.

Page down or Shift down arrow
	Move caret down by 10 lines, or to bottom line if less than
	ten lines from bottom.

Page up or Shift up arrow
	Move caret up by 10 lines, or to top line if less than ten
	lines from top.

Control down arrow
	Move caret to bottom line.

Control up arrow
	Move caret to top line.

Tab
	Move caret to next field. If at end of row, move to left field
	of next row.

Shift Tab
	Caret moves to previous cell in row.

Control shift Tab
	When in the header text of a column, add a new blank column at
	the right.

Return
	Move caret to next field. If at end of row, move to left field
	of next row. If at end of bottom row, create a new row and
	move to left field.

Control U
	Clear the contents of the current cell.

Backspace
	Delete character to left of caret.

Delete
	Delete character to right of caret.

Control shift Delete
	Delete the complete row of data and close up the rows.

Control shift Insert
	Insert a new blank row above the current caret row.





++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
The chart window
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


The data can be plotted in several different formats.

* Stacked bars
* Grouped bars
* Lines
* Stacked lines
* Pie chart	

The format of the chart can be changed at any time, and the layout
fine tuned, using the chart window menu, described below.


The chart window menu
---------------------

The upper section allows the chart to be replotted in a different
format. Examples of the formats are shown below.

Stacked bars
~~~~~~~~~~~~
This will replot the data in stacked bar chart format.

Grouped bars
~~~~~~~~~~~~
This will replot the data in grouped bar chart format. Alternatively,
following the arrow right allows you to select from a submenu just one
of the columns to be plotted.

Line graphs
~~~~~~~~~~~
This will replot the data in line chart format. Alternatively,
following the arrow right allows you to select from a submenu just one
of the columns to be plotted.

Stacked lines
~~~~~~~~~~~~~
This will replot the data in stacked line chart format.

Pie charts
~~~~~~~~~~
This will replot the data in pie chart format. Alternatively,
following the arrow right allows you to select from a submenu just one
of the columns to be plotted.

The next section has options to modify the layout of the chart.

Pie slices
~~~~~~~~~~
This option will only be available when a pie chart is showing, and
leads to a submenu.

When a pie chart is first plotted it will be shown with all the slices
together as a complete contiguous circle.

Choosing the option 'explode all' will draw the segments with their
centre moved away from the circle origin.

The option 'return all' will reverse this process.

There may be the situation where you want to emphasise only one or a
small number of pie slices. This cannot be done from the menu, but can
be done by simply double clicking on the slice which is to be moved
outwards. If more than one pie is showing, then the corresponding
slice in all the pies will be moved.

Any slice which has been moved out can be returned to the normal
position by double clicking on it again. The double click must be
within the area the slice would occupy in the normal position.

Display options...
~~~~~~~~~~~~~~~~~~
This opens a dialogue that allows a range of layout options to be
changed. Any changes will apply only to that specific chart, any other
charts displaying will be unchanged. The range of options available is
described in a separate page.

The final section allows the chart to be printed or saved as a
drawfile.

Print...
~~~~~~~~
This leads to a small dialogue.

This will show the currently active printer, and allows the number of
copies to be selected. Clicking Print will print the chart, using the
print format setting in the print tab of choices. If there is not an
active printer, the Print button will be shaded.

Save Drawfile
~~~~~~~~~~~~~
The arrow leads to a standard save as dialogue, allowing the chart to
be saved as a drawfile to disc or directly to another suitable
application.




++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
The chart window display options
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


When a new data set is created or loaded, it will inherit settings for
any chart attached to it from the global choices. The chart display
options window allows these settings to be overridden for an
individual chart.

At the bottom of the window are two buttons.

Apply
~~~~~
This will store and use the new settings only for the chart from which
the menu was opened. It will not change any other chart that is
currently showing, or any other chart attached to a new or different
data set. If the changes are to affect all charts, then use the
application wide Choices dialogue.

Cancel
~~~~~~
Close the dialogue and ignore any changes made since it was opened.


The options that can be changed are grouped under tabs in the window.

Chart
-----
This section contains settings for the chart display, in general.

Chart size
~~~~~~~~~~
This determines the size of the window used to display a chart.
Current sizes available are

640  480
800  600
1024  768
1280  1024
A4 landscape
A4 portrait

Shadows
~~~~~~~
When this is ticked, shadows will be added to bar and pie charts.
shadows.

Dashed grid lines
~~~~~~~~~~~~~~~~~
This determines whether the grid lines on the chart are drawn as a
solid line or as a dashed line. 

Thin lines on vdu
~~~~~~~~~~~~~~~~~
If this is selected, then the screen display will use 1 pixel wide
lines for all the lines on the chart, but when saving draw files and
printing will revert to the actual line widths as set in the choices
dialogue.

Black outlines on bars and pies
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When this is ticked, each component of a bar or pie chart will have a
black outline placed around its edge. The images below show part of a
bar chart plotted with and without black outlines.

Long axis-labels display
~~~~~~~~~~~~~~~~~~~~~~~~
This group of options controls what ChartDraw does when it thinks axis
label text is too long to fit easily on the chart. There are three
options.

* Offset alternate labels in a vertical direction
* Slant the text up from the left
* Slant the text down to the right

In addition, if one of the slant options has been chosen, the angle of
the slant can be set at 30, 45, or 60 to the horizontal.



Other
-----
This section contains some additional settings for particular types of
chart display. The tab is shown below.

In the Bar charts section:
-------------------------
Vertical
~~~~~~~~
When this is ticked, then the bars on a bar chart will be shown in a
vertical format. If not, the bars will be plotted horizontally. The
axes will change accordingly.



In the Line charts section:
--------------------------
Include origin in line chart
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When this is ticked, line charts will always be plotted from y = 0,
whatever the range of values in the data. If not ticked, then the axis
range will be chosen to cover the range of values, without necessarily
including the y = 0 axis.

Include symbols on lines
~~~~~~~~~~~~~~~~~~~~~~~~
If this is selected, then a symbol (e.g. square or circle) will be
placed at each data point, as well as a line joining each point. If
not selected, then the symbol will be omitted.

Use colours for data lines
~~~~~~~~~~~~~~~~~~~~~~~~~~
If this is selected, then the lines joining each data point will be
plotted in colour. If not selected, then the lines will be black.

Symbol size
~~~~~~~~~~~
If plotting a line chart, each set of data points can be shown as
symbols (e.g. square or circle). The size of the symbols can be set
(in os units) using the bump icons.



In the Pie charts section:
-------------------------
Show percentages
~~~~~~~~~~~~~~~~
This allows the display of percentages on pie charts to be switched
off or on. By default they are on.





++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Recent changes
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


Changes since version 3.50
--------------------------

version 3.52
~~~~~~~~~~~~
* Option to show or not show percentages on pie chart
* Chart key box now allows long legends to split at a space to give
  two rows
* Fix: Caret display when save as dialogue grabs caret and then gives
  it back
* Style guide change - each new input window opens 48 os units lower,
  rather than all being exactly on top of each other

version 3.51
~~~~~~~~~~~~
* Fix: Quit message and action when data is unchanged
* Fix: Filer running a chart file when ChartDraw is not running






++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Contact
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Contact
~~~~~~~
All communication about ChartDraw should be directed to Chris Johnson
(Email:chris@chris-johnson.org.uk). Suggestions for new features are
always welcome.

Web sites
~~~~~~~~~
Chris Johnson's web site is at
http://www.chris-johnson.org.uk/index.html, with his RISC OS software
at http://www.chris-johnson.org.uk/software/index.html.



++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Licence
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Copyright (c) 2014, Chris Johnson
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.

Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.



ChartDraw is  Chris Johnson, 2014  Email:chris@chris-johnson.org.uk


This document last modified on 5th May 2014









