FnPlotter
=========

RISC OS software by Chris Johnson
---------------------------------

Introduction
++++++++++++
What does FnPlotter do?
-----------------------
FnPlotter is a simple application that allows the entry of up to four
expressions in valid Basic format. These expressions can be evaluated
in a form suitable for plotting in the graphing application
!MultiPlot. The data can also be saved as a MultiPlot file, or as a
CSV file.

Installation
------------
Version 2 of !FnPlotter is now supplied as part of the !MultiPlot
installation, and so there is no requirement to install it separately.
If you have an older version of !FnPlotter already installed, it can
be deleted safely (or at least moved somewhere that is not normally
seen by the filer).

Using FnPlotter
---------------
!FnPlotter can be launched using the iconbar menu option in
!MultiPlot. !MultiPlot has the option in its choices to automatically
run !FnPlotter whenever !MultiPlot is run.

Once on the iconbar, clicking SELECT (left mouse button) on the
iconbar icon will open the main window. This is shown and described
here.

Clicking ADJUST (right mouse button) will open the Choices window.
This is described below.

Clicking MENU (middle mouse button) will open the iconbar icon menu.
See below.

The iconbar menu
----------------
The iconbar icon menu offers the following options.

Infothis 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.

Choices...will open the application choices dialogue, A
description of the features available is given in the Choices page.
The choices dialogue can also be opened by right clicking on the
iconbar icon.

Quitwill remove FnPlotter from the iconbar and terminate the
program.


The input/control window
++++++++++++++++++++++++

There are four writable fields into which you can enter up to four
functions. Empty fields will be ignored in any subsequent evaluation.
The functions must be in valid Basic format, and the variable must be
X. Basic keywords are all upper case, so FnPlotter will convert all
characters in the function to upper case before evaluating.

It is also necessary to enter the range of x that the function is to
be evaluated over. The minimum and maximum values to be used for x are
entered in the two appropriate fields.

Trigonometric values in Basic are expected to be expressed in radians.
To ease the conversion from degrees to radians, there is an option
button 'X values are degrees'. When ticked, FnPlotter will
automatically convert the entered values into radians before
evaluating the functions.

The lower section controls how FnPlotter will present the data in
MultiPlot format. You can choose to export the data as points or
lines, and select how many points or line segments will be used to
cover the range of X. By default these settings will be the same as
those in the choices window. Any changes to these settings in this
window will NOT effect the default choices settings.

If the option button Add to previous graph is ticked, then MultiPlot
will add the new graph data to the previous graph when a direct
transfer is carried out (assuming a previous transfer has actually
been done). This option always defaults to unticked and must be ticked
explicitly before a direct transfer is initiated. It will revert to
off when the transfer is completed. If the option is unticked, then
every transfer will result in a new graph window (up to the limit that
MultiPlot will allow).

At the bottom of the window are three buttons.

Close - This will simply close the window without any evalution
occurring.

Clear - This provides a quick means of clearing all the writable
fields

Graph - This will attempt to carry out the evaluation and transfer the
results directly to MultiPlot. MultiPlot must be on the iconbar for
this to be successful. If it is not, FnPlotter will raise a warning.
See the section on direct transfer for more information.

Closing the window
------------------
If the window is closed then all its contents will be cleared when the
window is reopened. In addition, the MultiPlot settings will revert to
the default settings. You can, of course, save all the contents of the
window using the menu (see below).

Input/control window menu
+++++++++++++++++++++++++
In the input window menu the following options are offered.

Graph (New)this is the same as the Graph button, described above,
and will attempt a direct transfer to MultiPlot, always opening a new
MultiPlot window. It is the equivalent of using the Graph button when
the Add to previous graph button is not ticked.

Graph (Add to last)this will attempt a direct transfer to
MultiPlot, and is the equivalent of using the Graph button when the
Add to previous graph button is ticked.

Save graph asleads to a submenu (shown at the right above)
offering the options to save the calculated data either as a MultiPlot
file or as a simple CSV file. The MultiPlot file can be loaded into
MultiPlot to show a graph of the data.

Save functionsleads to a standard Save as dialogue allowing the
contents of the input window to be saved as a simple text file. The
four functions, the X range, whether degrees or radians (if relevant)
and the MultiPlot settings are all saved in the file. The file can be
reloaded into FnPlotter subsequently, either by drag and dropping from
a filer window on to the iconbar icon, or in to the input window if
already open. All the details will be loaded into the input window.



The Choices window
++++++++++++++++++

The Choices window can be accessed either from the iconbar icon menu,
or by right clicking on the iconbar icon.

These choices control how the calculated data are transfered to
MultiPlot, or how the data is saved in the MultiPlot or the CSV file.

Applying to all formats you can select how many data points or line
segments are used to span the range between the minimum and maximum
values of X when the data are calculated.

In the case of MultiPlot format, you can opt to export the data as a
set of data points or as a data line by selecting the appropriate
radio button.

In the case of CSV file output, you can include the actual functions
in the output file as a reminder of what the data refers to by ticking
the option.

At the bottom of the window are three buttons.

Set - This will use the new settings as the default in any subsequent
calculations.

Save - This will use the new settings as the default in any subsequent
calculations and also save the settings so they are used as defaults
when !FnPlotter is run in the future.

Cancel - This will close the window without making any changes to the
current settings Remember, these settings (other than the CSV file
include function details option) can always be over-ridden at any time
from the main input window.


Transfer to MultiPlot
+++++++++++++++++++++

When you click on the graph button, or use the menu options, FnPlotter
attempts to send the data to MultiPlot in order to show a graph of the
function(s). This direct transfer is based upon the wimp message
protocol for inter-application transfer.

The first requirement is that MultiPlot is active, installed on the
iconbar. If MultiPlot is not active, then FnPlotter will issue a
warning asking for MultiPlot to be launched.

When the first transfer of a session occurs, a graph will be created
in a new MultiPlot window. During the interchange of messages,
MultiPlot will send FnPlotter a window handle for the new window.
FnPlotter will remember this handle. By default, a further transfer
will result in the data being shown in a new MultiPlot window. The
process is subject to the maximum number of open MultiPlot windows
allowed not being exceeded.

If you wish MultiPlot to specifically add the next set of data to the
previous graph, then ensure the option Add to previous graph is ticked
before pressing the graph button. If using the corresponding menu
option the setting for the Add to previous graph button is ignored,
the appropriate menu option over-riding this button setting. This will
be subject to the total number of allowable objects in a graph not
being exceded. However, if the MultiPlot graph has been closed, the
window handle will be invalid. If this is the case, then MultiPlot
will simply create a new window to display the new graph, and inform
FnPlotter of the newly created window handle.


Contact
=======
All communication about FnPlotter 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
=======

!FnPlotter
Copyright (c) 2017, 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.

Neither the name of the copyright holder nor the names of their
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.

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.


FnPlotter is  Chris Johnson, 2017
Email:chris@chris-johnson.org.uk 









