readme.txt

FuncPlotter is a combined Java application and applet for displaying two-dimensional plots of explic

========================================================================

FuncPlotter 2.0

Source code notes

========================================================================

1  Building FuncPlotter from source

To compile FuncPlotter, you require JDK 6.0 or later, which is available
from http://java.sun.com/javase/downloads/index.jsp

The source code distribution of FuncPlotter includes an Ant build file
(build.xml) that contains targets for compiling, JARing and running
FuncPlotter.  (The latter assumes the existence of a FuncPlotter
configuration file in a directory named config.)

------------------------------------------------------------------------

2  Organisation of the source code

The source code for FuncPlotter falls into two categories: code that
belongs to a named package and code that belongs to an unnamed (default)
package.  The partial use of named packages results from my reuse of the
packages in other projects.  If you modify any of the code in the
packages, you could add an appropriate prefix to the package name(s) or
you could "flatten" the code by removing the package declaration -- and
the corresponding import declarations -- from the relevant compilation
units.

The body of a class declaration is divided into sections, which are
ordered according to the following arbitrary scheme:
  Constants
  Enumeration types
  Member classes
  Static initialiser
  Constructors
  Class methods
  Instance methods
  Class variables
  Instance variables

Within sections, ordering is by access modifier:
  public - protected - private

------------------------------------------------------------------------

3  Program structure

I know that it's no substitute for a detailed UML class diagram ;-) but
here is a brief description of the structure of the program.

FuncPlotter was designed to be used as both a Java application and a
Java applet.  In order for it to be used as an applet, FuncPlotter's
main class (named FuncPlotter) is a subclass of java.applet.JApplet.
The main class instantiates a singleton class, App, which is initialised
to perform either as an application or as an applet.

FuncPlotter's document model is implemented by the class
FunctionDocument.  The FuncPlotter applet has a single instance of
FunctionDocument whereas the FuncPlotter application has a list of up to
64 documents, although only one document is displayed at a time.  Within
the App class, each instance of FunctionDocument is associated with an
instance of FunctionView.

When it is initialised as an application, App creates a frame of class
MainWindow (a subclass of javax.swing.JFrame) whose content pane is set
to an instance of TabbedPanel.  The tabbed panel is the container for
multiple instances of the FunctionView class.  When it is initialised as
an applet, App sets the content pane of the applet to an instance of
FunctionView.

FunctionView displays plots of functions in an instance of PlotPanel,
along with the GUI components that control the plot.

Each command in the main menu, pop-up menu and function-related command
buttons is implemented individually as a singleton subclass of
javax.swing.Action.  Commands that are derived from AppCommand are
performed by the App.doCommand( ) method, while commands that are
derived from DocumentCommand are performed by
FunctionDocument.doCommand( ).  When they are performed, most document
commands return a FunctionDocument.Edit object, which is added to the
list of the document's edits for use by the Undo and Redo commands.

Configuration is performed by the singleton class AppConfig, which
accesses a configuration file through the class ConfigFile.

Expressions are parsed and the resulting expression tree is evaluated
within the class Expression.

The reporting of exceptions is based on the class AppException in the
exception package.  When an instance of AppException (or subclass) is
thrown, it is constructed with an error identifier -- an instance of an
enumeration type, ErrorId -- that is mapped to a message when an
exception is reported.

Classes that have the prefix "F", such as FComboBox, are wrappers for
Swing components that initialise the component with the appropriate
font, enumerated by AppFont.

------------------------------------------------------------------------

4  Internationalisation and localisation

I haven't availed myself of the Java localisation facilities when
displaying numbers in FuncPlotter: the key numeric values (scale
markings, cursor coordinates and interval endpoints) are all converted
to strings without regard to locale.  That is, the strings are composed
of Western digit characters, '0'..'9', and the '.' radix point.

I've made a half-hearted attempt at i18n by putting in place the code to
handle languages that have a horizontal, right-to-left orientation (eg,
Arabic, Hebrew).  By itself, this is useless since the strings used by
FuncPlotter are all hard-coded in English, but it's intended to make
things easier for anyone who wants to convert the source code for a
right-to-left language.  Because I don't know the conventions for
right-to-left locales, all I've done is to ensure that the GUI is laid
out from right to left in a locale that is associated with a
right-to-left language.  If configured to do so, the static method
App.applyOrientationByLocale( ) applies locale-dependent orientation to
a component and all of its descendants.

For anyone who wants to translate the strings in the source code into a
language other than English, the language-specific strings can be found
in three areas within a source file: static final variables in a
"Constants" section, enum constants in an "Enumeration types" section,
and final variables within a method.

------------------------------------------------------------------------

5  Documentation

... or, rather, the lack of it.

FuncPlotter was originally a tool for my personal use, and the sparse
level of comments within the source code reflects this.  (My policy on
putting comments in code that I write for myself is to incorporate only
enough of them to remind me of what the code does when I return to it
after a few months' absence.)  One particularly grave omission is that
there are almost no Javadoc-type documentation comments in the source
code.

------------------------------------------------------------------------

6  Reporting bugs

The FuncPlotter project is hosted by SourceForge.net.  You can submit
bug reports, requests for enhancements (RFEs) and suggestions for
improvements through the facilities on the FuncPlotter project page of
the SourceForge website:
  http://sourceforge.net/projects/funcplotter/
Follow the links labelled "Bugs" or "RFE" / "Feature requests".

When reporting a problem with FuncPlotter, please include enough
relevant information to enable the problem to be reproduced.  You should
include at least the following information:
 * FuncPlotter version number
 * platform and OS version number
 * Java version number
 * a description of the problem.
A Java stack trace, if one is available, would be helpful.

You can make comments about FuncPlotter by using the public Open
Discussion forum, accessible through the FuncPlotter page of the
SourceForge website.

You must be logged in as a registered user of SourceForge in order to
report bugs, to request enhancements or to post a message to the forum.
Registration for SourceForge, which isn't very onerous, offers a measure
of protection against the abuse of their facilities.

------------------------------------------------------------------------