FuncPlotter 2.4 : Manual
Table of contents
You must have JavaScript enabled in your browser to generate the table
of contents.
1 Introduction
[ Table of contents ]
FuncPlotter is a combined Java application and applet for displaying
two-dimensional plots of explicit functions in one variable (ie,
functions of the form y = f(x),
where f(x) is an arbitrary function composed from a
set of common mathematical operators). It is distributed under version
3 of the GNU General
Public License; for details, see the file license.txt
that is included in the FuncPlotter distribution.
FuncPlotter has the following features:
-
It can be used either as a Java application or as a Java applet that
is included in a page of HTML or XHTML.
-
Up to 20 functions can be plotted simultaneously. The colour of each
plot can be specified.
-
When used as an application, FuncPlotter can save a set of up to 20
functions to a file and can load files saved in this way. The files
are saved either as XML or in a simple text format, allowing you to
create and to edit files with a text editor. (The ability to load and
to save files is not available in applet mode.)
-
In application mode, multiple documents (sets of functions) can be
open simultaneously in a tabbed window. (Multiple documents are not
supported in applet mode.)
-
Changes that are made to a document can be undone and redone.
-
When the mouse cursor is over the plot area, the x and
y coordinates at the cursor are displayed.
-
Plots can be scrolled by clicking on buttons, rotating the mouse
wheel, dragging the mouse or pressing keys.
-
Plots can be zoomed in and out. Each of the x and y
dimensions has its own independently selectable zoom factor.
-
Plots can be exported as an image file in PNG format.
In this document, FuncPlotter's two operating modes are referred to
as application
mode and applet
mode. Any part of this document that is specific to one
mode is drawn with left and right borders in the appropriate colour.
The website of the FuncPlotter project is at http://funcplotter.sourceforge.net/
.
2 Requirements
[ Table of contents ]
To run as an application, FuncPlotter requires a Java runtime
environment that supports Java 1.6, such as Sun's Java Runtime Environment (JRE),
version 6.0 or later.
To run as an applet, FuncPlotter requires a web browser that supports
Java 1.6 applets. Plug-in components for Java applets are available
for most common browsers. Sun's Java Plug-in is included in JRE.
3 Contents of the distribution
[ Table of contents ]
The following files are included in the distribution:
- funcPlotter.jar
-
The executable JAR (Java archive) file that is used for both the
FuncPlotter application and the applet.
- funcPlotter.conf
-
The configuration file for FuncPlotter,
which contains the default values for the configuration properties.
- license.txt
-
A copy of the GNU General Public License, version 3 — the
license under which FuncPlotter is distributed.
-
doc/manual.html, doc/images/dirTree.png, doc/images/valid-xhtml11.png,
doc/scripts/toc.js, doc/style/funcPlotter-manual.css,
doc/style/puckfist-manual.css, doc/style/puckfist-common.css
-
This manual, its image files, script and stylesheets. Any
modifications to the manual for the latest version of FuncPlotter will
appear in the online version of the document, to which there is a link
on the FuncPlotter
website.
- dtd/functionList.dtd
-
The DTD (document type definition) of a FuncPlotter document in XML
format. (FuncPlotter does not use the DTD; it is provided only for
reference.)
- example/example.xml, example/example.txt
-
Examples of a FuncPlotter document in the two formats supported by the
application. The examples both contain the same arbitrarily chosen
functions.
-
example/applet1.html, example/applet2.html, example/applet3.html,
example/applet4.html
-
Examples of how the FuncPlotter applet can be included in an HTML
document. The first three files correspond to one of the numbered
HTML fragments, HTML fragment 1, HTML fragment 2 and HTML fragment 3. The fourth file is an
example of how JavaScript can be used to generate an HTML
<object> element according to the type of browser.
- images/funcPlotter.png, images/funcPlotter.ico
-
A 48×48-pixel PNG image and a 48×48-pixel Windows-format
icon that can be used to customise a desktop icon for the FuncPlotter
application.
4 Installing and running FuncPlotter
[ Table of contents ]
Note: FuncPlotter is distributed without an
automated means of installation. Because of this, the instructions
below assume a certain level of technical knowledge. In particular, the
installation of FuncPlotter as an application requires knowledge of
environment variables and command lines appropriate to the system on
which FuncPlotter is to be installed, while the installation of
FuncPlotter as an applet requires knowledge of how Java applets are
included in HTML.
FuncPlotter consists of a single JAR (Java archive) file,
funcPlotter.jar. It may be used with a configuration file,
funcPlotter.conf, which contains user preferences. Of the files listed in the
contents of the distribution, only the JAR file
is required.
The installation of FuncPlotter consists of two stages: copying the JAR
file — and, optionally, the default configuration file — to
your system, and providing a means of invoking the JAR file. The more
advanced topic of configuring FuncPlotter after installation is dealt
with in the section on configuration.
The first stage is simple: copy the file funcPlotter.jar to
a suitable location on your system. The next stage depends on whether
you want to use FuncPlotter as an application or as an applet. (The
same copy of funcPlotter.jar can be used in both modes, but
the method of invocation differs between application and applet.)
4.1 Using FuncPlotter as an application
The recommended way of running FuncPlotter as an application is to
invoke the java launcher tool from a command line, which
may be included in a batch file. Configuration
properties (including the location of a configuration file) may be
specified in the command line.
4.1.1 Linux/UNIX
Assuming that your PATH environment variable includes the
path to the java tool and that you have copied
funcPlotter.jar to the directory
/home/slothrop/bin/funcplotter/, the command
java -jar /home/slothrop/bin/funcplotter/funcPlotter.jar
will run the FuncPlotter application.
The file funcPlotter.png can be used as the icon for the
FuncPlotter application.
4.1.2 Windows
The FuncPlotter application does not require a console window, so you
can use the javaw launcher rather than the
java launcher unless you particularly want a console
window. Assuming that your PATH environment variable
includes the path to the javaw tool and that you have
copied funcPlotter.jar to the directory
C:\Program Files\FuncPlotter\, the command
javaw -jar "C:\Program Files\FuncPlotter\funcPlotter.jar"
will run the FuncPlotter application.
The file funcPlotter.ico can be used as the icon for the
FuncPlotter application.
4.1.3 Specifying files on the command line
You can have the FuncPlotter application open one or more files on
startup by specifying the files on the command line after the name of
the JAR file. Thus, extending the example for Linux/UNIX given above,
the command
java -jar /home/slothrop/bin/funcPlotter/funcPlotter.jar ~/fp/hyperbolic.xml
would launch FuncPlotter and open the file
hyperbolic.xml.
Note that the Java launcher expands command-line arguments in the same
way as a UNIX shell: pathnames that contain wildcards are replaced
with multiple pathnames of files that match the pattern.
4.2 Using FuncPlotter as an applet
FuncPlotter can be run as an applet by including an
<applet> or <object> element in
an HTML or XHTML document. Configuration
properties may be specified in applet
parameters — <param> elements within the
<object> or <applet> element.
Under strict HTML 4.01 and XHTML, a Java applet must be included in
HTML or XHTML using the generic <object> element;
the <applet> element is deprecated. As described
in the HTML
4.01 specification, the inclusion of Java applets in HTML with the
<object> element is straightforward. In reality,
however, things are rarely so simple, especially where Microsoft is
concerned. In its wisdom, Microsoft has decided not to include
support for Java applets as <object> elements in
Internet Explorer in the straightforward way described in the HTML
specification. Instead, if you are using Internet Explorer on Windows
and want IE to render a Java applet using the
<object> element, the Java Plug-in must be
specified as the classid attribute of the
<object> element, and the applet and its codebase
as <param> elements. This awkward, proprietorial
method is not compatible with conforming browsers like Firefox or
Opera, so you must either sacrifice (X)HTML conformity or have two
separate pages, one for IE and one for browsers like Firefox or Opera
that recognise the application/x-java-applet MIME type.
Alternatively, you can use JavaScript to detect the browser type and
to generate the appropriate HTML.
Sun's guide
to including Java applets in HTML says that "the [HTML 4.01]
specification is vague about how browsers should implement the
object tag to support Java applets, and browser support
is currently inconsistent." The specification of the
<object> element (HTML
4.01, section 13.3) appears to be sufficient for the
implementation of support for Java applets — after all, it's
no less detailed or more ambiguous than the specification of the
<applet> element, which, because of its widespread
support, is Sun's recommended means of including applets in HTML.
The following fragments of HTML illustrate different ways in which the
FuncPlotter applet can be included in a page of HTML. Three HTML
files, applet1.html, applet2.html and
applet3.html, are included in the FuncPlotter
distribution as examples of the use of each fragment. A fourth HTML
file, applet4.html, illustrates the use of JavaScript to
generate an <object> element — either
fragment 1 or fragment 2, according to the type of browser. In the
fragments and the example files, the values for the
codebase attribute and the app.configPath
parameter assume the following arbitrary directory tree:
All three fragments contain a plot size parameter,
app.plot.size, and a function list size parameter,
app.function.listSize. If a configuration file exists
and the security manager permits it to be read, the value of the
property in the configuration file will override the value that is
specified in the <object> or
<applet> element.
4.2.1 HTML fragment 1
This uses the <object> element to include
FuncPlotter as an applet in an HTML document. It conforms to the HTML
4.01 Strict and XHTML 1.1 DTDs, but it won't work with Internet
Explorer.
The codetype attribute specifies the MIME type of the
object: a Java applet. The version number (1.6) indicates the minimum
version of JRE required by the applet.
<object codetype="application/x-java-applet;version=1.6"
classid="java:FuncPlotter"
codebase="jar/"
archive="funcPlotter.jar"
width="937" height="537">
<param name="app.configPath" value="../../config"/>
<param name="app.plot.size" value="480, 480"/>
<param name="app.function.listSize" value="24, 12"/>
The browser may not support Java applets as <em><object></em>
elements.<br/>
</object>
4.2.2 HTML fragment 2
This also uses the <object> element to include
FuncPlotter as an applet in an HTML document. It conforms to the HTML
4.01 Strict and XHTML 1.1 DTDs. It will work with Internet Explorer
but not with Firefox.
The value of the classid attribute was obtained from the
JDK documentation. It is associated in the Windows registry with the
highest installed version of Java Plug-in.
The <object> element should properly have a
codebase attribute that specifies a URI from which an
appropriate version of Java Plug-in can be loaded if it is not already
installed. The example assumes that Java Plug-in is already
installed.
<object classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"
width="937" height="537">
<param name="code" value="FuncPlotter"/>
<param name="codebase" value="jar/"/>
<param name="archive" value="funcPlotter.jar"/>
<param name="app.configPath" value="../../config"/>
<param name="app.plot.size" value="480, 480"/>
<param name="app.function.listSize" value="24, 12"/>
The FuncPlotter applet requires a browser with Java Plug-in 6.0 or
later installed.<br/>
</object>
4.2.3 HTML fragment 3
This uses the <applet> element to include
FuncPlotter as an applet in an HTML document. It conforms to the HTML
4.01 Transitional DTD. It is compatible with Internet Explorer,
Firefox and Opera.
<applet code="FuncPlotter"
codebase="jar/"
archive="funcPlotter.jar"
width="937" height="537">
<param name="app.configPath" value="../../config"/>
<param name="app.plot.size" value="480, 480"/>
<param name="app.function.listSize" value="24, 12"/>
The browser may not support Java applets as <em><applet></em>
elements.<br/>
</applet>
4.2.4 Using JavaScript to generate an
<object> element
If you want to include the FuncPlotter applet in a document that
conforms to the strict HTML 4.01 or XHTML specification, you must use
the <object> element to do so. If you also want a
single document that can be used with a range of popular browsers, the
best way to do this seems to be with JavaScript. The file
applet4.html shows how this can be done by including the
script within an HTML document. It would be better to remove the
JavaScript to a function in a separate file, and to invoke the
function from an event handler such as an onload handler
in the <body> element, which is the method that is
used by the applet page
on the FuncPlotter website.
If a script is used to generate the HTML that includes the FuncPlotter
applet in a document, it can also extract configuration parameters for
the applet from the query part of the document's URL, then
generate the <param> elements for the parameters,
avoiding the need to include the applet's configuration parameters
in the HTML.
4.2.5 Minimum applet dimensions
In order for the FuncPlotter applet to be displayed correctly, you
must set the width and height attributes of
the <object> or <applet> element
that invokes the FuncPlotter applet so that the dimensions of the
applet are not less than the minimum required by FuncPlotter. If the
applet dimensions are too small, the plot panel and function list will
be reduced to their minimum size, and FuncPlotter's display will
appear to have imploded. To discover the minimum dimensions of the
FuncPlotter applet, run the applet: the minimum dimensions are
displayed on the Java console and, if either dimension is too small,
in an error message. Note that the minimum dimensions may change as a
result of modifying some of FuncPlotter's configuration properties
(eg, plot size or fonts), and you will have to modify the
width and height attributes of the
<object> or <applet> element
accordingly.
4.2.6 Startup parameters
The applet can be configured to display one or more specified
functions on specified x and y intervals when it
starts up. The properties app.startup.xInterval,
app.startup.yInterval and
app.startup.function<index> are used for
this purpose. In the function property, <index> is the
zero-based index of the function (eg,
app.startup.function2 denotes the third function).
The syntax of the x and y intervals and the function
definitions is the same as that of the interval and function
definitions in a text-format file except
that the x and y intervals do not have a prefix of
"@x" or "@y".
4.2.7 Performance problems
A Java application with a graphical user interface (GUI), such as
FuncPlotter, usually has its own top-level window. An applet, on the
other hand, usually runs in a window of a browser, and the components
of the applet's GUI become components of the browser's window.
Problems may arise from the interaction of the applet's components
with the browser's window; one notable problem is the transfer of
keyboard focus. FuncPlotter follows the recommendation in the Java
documentation that components should request focus rather than grab
it, though the focus may sometimes "go missing" in some
browsers as result of this. Two seemingly related problems are:
-
when the applet starts up, the form of the mouse cursor sometimes
gets stuck as a cross-hair — the form it takes when the cursor
is over the plot panel — until one of the applet's
components gains focus; and
-
the keyboard shortcuts for the Undo, Redo and Grid commands are
ignored until the a component in the FuncPlotter display is
explicitly given focus by clicking on it.
The form and extent of the focus-related problems varies between
browsers.
4.3 Uninstalling FuncPlotter
FuncPlotter does not have an automated means of uninstallation. To
remove it from your system, delete the file funcPlotter.jar
from the location to which you copied it when you installed FuncPlotter.
If you want to remove FuncPlotter completely, you should also delete the
configuration file, funcPlotter.conf, which may be at its
default location.
5 Security
[ Table of contents ]
Some of the functionality of FuncPlotter — in particular, access
to the file system and clipboard — may be restricted by the
protection mechanisms of the Java virtual machine on which it is run.
Different restrictions are likely to apply according to whether
FuncPlotter is run as an application or as an applet: read the relevant
section before you run FuncPlotter.
FuncPlotter is distributed as a signed JAR file. The JAR file
is self-certificated (ie, it's signed by the author of the software,
not with a certificate from a recognised certification authority). The
purpose of signing the JAR file is to allow users that trust its digital
signature to access features of FuncPlotter that are disabled for
untrusted code. As a general policy, it is recommended that you trust
the signature of a JAR file no more than is necessary to obtain the
functionality that you require. In the case of FuncPlotter, if you can
do without accessing the file system (to read a configuration file, or
to read and write documents) and the clipboard (to copy and paste
expressions), there is no need to trust FuncPlotter when prompted to do
so.
Because FuncPlotter's source code is freely available, it is
possible, without much effort, to build a modified version of
FuncPlotter that contains malicious code, and to distribute the
resulting JAR file with a bogus signature, so the presence of a
signature does not in itself confer any security. The recommended
method of verifying the integrity of FuncPlotter is to verify the SHA-1
digest of the entire FuncPlotter distribution against the values in the
release notes on SourceForge.
The security restrictions that are imposed on an application running
on a Java virtual machine are determined by the security manager and
security policy that are in force on a particular system. If no
security manager is specified, the default security manager will
permit all the functionality of FuncPlotter (that is, FuncPlotter will
be implicitly trusted); otherwise, similar restrictions to those
imposed on an applet are likely to apply.
Browsers generally have a security manager that restricts access to
the file system and clipboard for untrusted applets. This section
assumes that you are using Sun's Java Plug-in to run the applet
from within a browser.
When the FuncPlotter applet is run, the Java plug-in will detect that
the JAR file is signed and — unless you have previously agreed
always to trust its signature — will inform you that the
certificate is invalid, is not trusted or cannot be verified because
it was not issued by a recognised certification authority. It will
then ask you whether you want to run the applet. (The wording of the
response of the Java plug-in to a signed applet varies with the
browser and the version of the Java plug-in.) If you don't need
the features that are enabled as a consequence of trusting the applet,
don't agree to trust it, especially if you don't know its
provenance. Be aware that, if you agree always to trust the signed
applet, you will be implicitly granting trust to all other applets
that have the same signature, so it's important that you are sure
of the authenticity of the signature before you do so. (You can use
the Java control panel to remove a no-longer-trusted certificate, but
the damage may already have been done by then.)
Sun's Java Plug-in adds the label "Java Applet Window"
to windows that are created by untrusted applets. A window includes a
tool-tip or a pop-up menu that extends beyond the bounds of the
applet.
6 Configuration
[ Table of contents ]
When it starts up, FuncPlotter is configured from different sources
according to whether it is run as an application or as an applet.
Both the application and the applet can get their configuration from a
configuration file whose location may be explicitly specified. In
addition, the application can be configured with command-line properties
(specifically, the command line that is used to run the Java launcher),
and the applet can be configured with parameters of the HTML
<object> or <applet> element.
The recommended method of setting the properties in a configuration file
is with the Options > Preferences command
from within the FuncPlotter application. Like the other menu commands,
this command is not available when FuncPlotter is run as an applet,
although it is possible to run FuncPlotter as application in order to
generate or to edit a configuration file that is used by FuncPlotter in
applet mode. Command-line properties and HTML applet parameters must
necessarily be edited manually; the form of the property values is given
in the appendix on configuration properties, and
it can also be inferred from the sample configuration file.
6.1 Command-line properties
When FuncPlotter is run by means of the java launcher,
configuration properties may be specified in the command line using
the standard Java form
-Dname="value"; eg,
-Dapp.plot.size="480, 480". (The
quotation marks around the value aren't necessary if the value
doesn't contain spaces.) FuncPlotter's command-line
configuration properties all have the prefix
"app.". A list of all the properties that are
recognised by FuncPlotter is given in the appendix on configuration properties.
6.1.1 The app.configPath property
One particular property, app.configPath, is used to
specify the directory that contains a configuration file:
-
If the
app.configPath property exists and the property
value is the empty string, FuncPlotter will start without a
configuration file.
-
If the
app.configPath property exists and the property
is not empty, FuncPlotter will look for a configuration file on the
path specified by the property. The property value is taken to be a
list of directories separated with the system-dependent path
separator (":" on Linux/UNIX, ";" on Windows).
The directories are searched in the order in which they appear in
the list.
-
If the
app.configPath property does not exist,
FuncPlotter will look for a configuration file at two other locations.
If the configuration file were located in a directory named
config in the user's home directory, the sample
command lines given above would become:
| Linux/UNIX: |
java -Dapp.configPath="~/config" -jar
/home/slothrop/bin/funcplotter/funcPlotter.jar
|
| Windows: |
javaw -Dapp.configPath="~/config" -jar
"C:\Program Files\FuncPlotter\funcPlotter.jar"
|
The value of the app.configPath property may contain special constructs for system properties,
environment variables and the user's home directory.
6.2 Applet parameters
When FuncPlotter is run as an applet, configuration properties may be
specified as <param> elements within the
<object> or <applet> element
that is used to include the FuncPlotter applet in an HTML document.
The <param> element takes the form <param
name="name"
value="value"/>. FuncPlotter's
applet configuration properties all have the prefix
"app.". A list of all the properties that are
recognised by FuncPlotter is given in the appendix on configuration properties.
6.2.1 The app.configPath property
One particular property, app.configPath, is used to
specify the directory that contains a configuration file. If the
app.configPath property exists, FuncPlotter will look for
a configuration file at that location.
If the scheme of the URL specified by the app.configPath
property is "file", the property value may
contain special constructs for system
properties, environment variables and the user's home directory.
If you run FuncPlotter as an unsigned or untrusted applet, your
browser's security manager may prevent the applet from accessing
some system properties or environment variables. In such cases, the
property or variable will have the value of the empty string, but
it's likely that the same security policy would also prevent the
applet from reading a configuration file.
6.3 Configuration file
The configuration file, which must be named
funcPlotter.conf, is an XML file that is ordinarily written
by FuncPlotter but can be edited manually if you know what you're
doing. (It can also be edited manually if you don't know
what you're doing, but this is discouraged.) FuncPlotter
doesn't require a configuration file — or any of the
alternative methods of configuration, for that matter: it uses a default
value for any configuration property that is missing from the source(s)
of configuration. Similarly, if it finds a property value to be
invalid, FuncPlotter will display a message to this effect and use its
default value.
In application mode, a configuration file takes precedence over
configuration properties in the command line; that is, if the same
property is specified as a command-line property and in a
configuration file, the value from the configuration file is used.
If the configuration has changed when you exit the application
normally (ie, using the File > Exit command or an equivalent),
FuncPlotter will save its configuration to a configuration file. If a
configuration file was read on startup, it will overwrite that file;
otherwise, it will write a configuration file to the default directory
described above.
A configuration file can be written explicitly with the Save
Configuration command within the Preferences dialog.
In applet mode, a configuration file takes precedence over HTML applet
parameters; that is, if the same configuration property is specified
as an HTML parameter and in a configuration file, the value from the
configuration file is used.
6.3.1 Location of the configuration file
When it starts up, the FuncPlotter application is informed of the
location of the configuration file with the app.configPath property, which
may be set on the command line that runs the java
launcher. The existence of a system property with the key
app.configPath determines the locations that are searched
for a configuration file:
-
If a property with the key
app.configPath exists,
FuncPlotter will look for a configuration file on the path specified
by the property, unless the property value is the empty string. If
a configuration file is not found in any of the directories
specified by the app.configPath property, an error
message is displayed.
-
If a property with the key
app.configPath does not
exist, FuncPlotter will look for a configuration file in the current
working directory before trying the default directory. The current
working directory (the directory specified by the environment
variable $PWD on Linux/UNIX systems) depends on the
system and the way in which FuncPlotter was invoked. The default
directory is ${user.home}/.puckfist/funcplotter, where
${user.home} is the user's home directory (the
directory specified by the environment variable $HOME
on Linux/UNIX systems or %USERPROFILE% on Windows
systems).
The FuncPlotter applet is informed of the directory that contains the
configuration file with the app.configPath property, which
may be set as a parameter in the HTML <object> or
<applet> element. A browser's security manager
may prevent an untrusted applet from reading a configuration file.
7 Document windows
[ Table of contents ]
FuncPlotter uses a tabbed document interface to display multiple
documents in application mode. This interface uses a single tabbed
window so that only one document — referred to as the
current document — is visible at any one time. You can
select a document by clicking on its tab, or you can select a document
from the alphabetically ordered list that is displayed by clicking on
the down-arrow button in the tab bar. Pressing Ctrl+Tab or
Ctrl+Shift+Tab will display a list of documents in the centre of the
window, which can be navigated with subsequent presses of Ctrl+Tab or
Ctrl+Shift+Tab until the Ctrl key is released.
You can copy x and y intervals between documents
using the command Edit > Copy Intervals to
Other Documents.
The size of the main window cannot be changed directly, but it can be
changed indirectly by modifying the dimensions
of the plot panel and the dimensions of the list of functions.
Changes to these properties will not take effect until the next time
that FuncPlotter is run. Some of the other configuration properties
(eg, the fonts) may also affect the size of the main window.
8 The display
[ Table of contents ]
8.1 Plot panel
FuncPlotter's display consists of a main window divided into several
panels. On the leading side of the main window (left in left-to-right
locales, right in right-to-left locales) is the plot panel, which
contains plots of the current set of functions. By default, the
functions are drawn over a grid of horizontal and vertical lines, but
the grid can be hidden from view. The
scales of the horizontal dimension (the x scale) and the
vertical dimension (the y scale) are always linear.
Like the other numeric values that are displayed by FuncPlotter, the
scale markings are subject to rounding. The most important consequence
of rounding is that, while the displayed value of the scale marking is
always the nearest value (after rounding) for the x or
y pixel coordinate of the scale marking, there may be another
pixel coordinate that is nearer to the displayed value of the scale
marking. If, as a result of rounding, two or more consecutive scale
markings have the same value, the duplicate values are not displayed.
The text of an x-scale marking is either omitted or truncated
according to the plot.truncateXScaleText
configuration property if it would overlap the text of the previous
marking. The text of a y-scale marking is truncated if it is
too wide to be displayed in full. If the text of a scale marking is
truncated or omitted, the full text is displayed when the mouse cursor
is moved over the region of the truncated or omitted text.
In addition, the following aspects of the plot
panel are configurable:
- the width and height of the plot,
- whether the grid is visible or hidden by default,
- the colours of the elements of the panel.
Although the plot panel has no scroll bars, the plot can be scrolled by
four methods:
-
Click on the scroll buttons in the scroll/zoom panel.
-
Rotate the mouse wheel. The normal (forwards–backwards)
rotation of the mouse wheel scrolls the plot in the vertical
direction. If the Ctrl key is pressed while the mouse wheel is
rotated, the plot is scrolled in the horizontal direction.
-
Hold down the left mouse button and drag the mouse.
-
Press the arrow keys when the plot panel has keyboard focus.
If the plot panel has focus, its border is two pixels wide, in the
colour specified by the
plot.colour.focusedBorder
configuration property; otherwise, its border is grey and one pixel
wide.
The unit of scrolling is half a grid division in each direction.
To maintain consistency between actual and displayed interval values
when the plot panel is scrolled or zoomed, the actual x and
y intervals are updated to values that are as close as possible
to the intervals that are displayed in the interval fields (see below).
The plot.numFractionDigits
configuration property determines the granularity of an interval and
affects the ability to scroll or to zoom: the more fraction digits, the
further you are able to zoom in. As you zoom in, the scrolling
increment (half a grid division) approaches the difference between
distinct values in the interval. Near the limit, scrolling behaviour
becomes irregular, and the ability to scroll eventually disappears.
8.1.1 How functions are plotted
FuncPlotter plots a function
y = f(x) by evaluating y
for the values of x that correspond to pixel divisions on the
current x interval, and drawing line segments between
successive points, (xn, yn)
and
(xn+1, yn+1).
FuncPlotter uses the mathematical operators and methods of the Java
language to evaluate f(x). The Java operators and
methods, which are based on the IEEE 754 standard, sometimes result in
an infinity (positive or negative) or a Not-a-Number (NaN)
value. For example, division of a finite number by zero results in a
signed infinity, whereas taking the natural logarithm of a negative
number with the method java.lang.Math.log results in NaN.
When evaluating an expression, an NaN that appears as an intermediate
result is transmitted to the final result. If the value of
yn = f(xn) is
an NaN, FuncPlotter does not draw a line segment between
(xn−1, yn−1)
and (xn, yn) or between
(xn, yn) and
(xn+1, yn+1).
This behaviour is usually what you would expect; for instance, the plot
of the function y = ln x is confined to
the right of the y axis.
Expressions for f(x) that involve operators such as
acos or sqrt are plotted only for the
principal values of f(x) that are returned by the
underlying Java methods. (In the case of
y = acos x, y is confined to
the range [0, π], whereas for
y = sqrt x, y is confined to
the positive root of x.)
8.1.2 Problems inherent in the method of plotting functions
Two significant problems in the way in which FuncPlotter plots functions
have come to light so far. These problems are not bugs but unwanted
"features" — consequences of the design of the software.
The join-the-dots approach works adequately
for most functions, but periodic functions and functions with an
infinite discontinuity each have a problem associated with them.
When plotting periodic functions, FuncPlotter exhibits the problem of
aliasing, which occurs when the sample period — the
difference between successive x values at which the function is
evaluated — is greater than or equal to twice the period of the
function. This effect can be observed by plotting a simple periodic
function, such as y = sin x, and
repeatedly reducing the magnification. The problem of aliasing could be
mitigated by oversampling, but it would still occur eventually, and the
oversampling would increase the computational burden of plotting a
function.
Functions that have an infinite discontinuity — eg,
y = (x + 1) / (x − 1),
which has a vertical asymptote at x = 1 —
suffer from a "cropped tail": the plot of the function stops
some way short of its (unattainable) goal of positive or negative
infinity. If xd is a value of x in the
x interval of the plot at which there is an infinite
discontinuity, {xn} is the set of values of
x for which f(x) is evaluated by FuncPlotter
when plotting y = f(x), and
xnd is the member of {xn} that
is nearest to xd, then the "cropped tail"
artifact occurs when f(xnd) lies within the
y interval of the plot or when
f(xnd) is NaN. The severity of the problem
is determined by how close xnd is to
xd; hence, the problem is sensitive to changes in
the x interval. (For instance, a "tail" may appear
and disappear as a plot is scrolled horizontally.) Like the problem of
aliasing, the problem of infinite discontinuities could be mitigated by
oversampling.
Functions that are periodic and have infinite discontinuities
(eg, y = sec x) don't look too good
when drawn by FuncPlotter at low magnification.
8.2 Function panel
At the top the display beside the plot panel is a panel containing a
list of the functions that comprise the current document, and a group of
buttons that relate to the list of functions.
Each row of the function list contains an expression for
f(x) next to a sample of the colour in which the
function is plotted; see Expressions for
details of the syntax and semantics of expressions. An expression is
truncated with an ellipsis if it is too long to fit within the width of
the function list. If an expression is truncated, the full expression
can be displayed in a pop-up window by holding down the Ctrl key and
pressing the left mouse button while the mouse cursor is over the
expression.
If the function is hidden, the colour sample is absent. The colour of
each function can be edited. The default
function colours are configurable.
Functions are plotted in reverse order from the order in which they
appear in the list. This means that the function at the top of the list
will be drawn on top of all the functions that are below it in the list.
The position of a function in the list can be changed by dragging the
function up or down the list with the left mouse button, or by pressing
Ctrl+Up or Ctrl+Down. A command is provided
to reverse the order of the functions in the list.
Only one function in the list can be selected at a time.
Double-clicking on a function in the list will bring up an Edit Function dialog for that function.
The size of the list of functions — the number of columns and rows
in the viewable region of the list — is specified as a
configuration property, function.listSize.
Directly below the list of functions is a group of buttons that can be
used to issue commands that relate to the list of
functions.
8.3 Mouse cursor coordinates
Below the function panel is a panel containing a single field labelled
"Cursor:". When the mouse cursor is over the plot panel, this
field displays the x and y coordinates at the mouse
cursor. To conserve horizontal space, the coordinates are displayed in
two rows. The coordinates are formatted according to the scheme
described in Numeric values.
8.4 Controls
Below the cursor panel is a panel in which the x and y
intervals of the plot panel are displayed. The intervals, which are set
implicitly by scrolling and zooming the plot panel, can also be set
explicitly by entering values in the interval fields. To update an
interval after editing a value in an interval field, press the Return
key while one of the interval fields has keyboard focus (ie, the text
cursor is within an interval field). The minimum and maximum values of
the endpoints of both the x and y intervals are
1.0E−100 (10−100) and 1.0E100 (10100)
respectively.
Below the intervals panel is a panel containing scroll buttons, zoom
buttons and combo boxes for selecting the zoom factor. The arrow
buttons scroll the plot in the direction of the arrow; the circle button
centres the plot around the origin, (0, 0). The zoom buttons for each
dimension have a zoom factor associated with them, which can be selected
from a list of preset values using the combo box beside each pair of
zoom buttons.
8.5 Minus sign
In components of the main window and Function dialog, a minus sign in
numerical values and expressions is displayed with (in order of
preference) a minus sign (U+2212) or en dash (U+2013) character if one
of those characters can be displayed in the component's font. If
neither character can be displayed, a hyphen-minus (U+002D) character is
used.
9 Commands
[ Table of contents ]
The commands that appear in the menu bar of FuncPlotter's main
window are only available when FuncPlotter is run as an application.
9.1 File menu
The commands in the File menu are mostly standard and
self-explanatory, but note the following:
-
The Open command brings up a file-selection dialog in which you
can choose the file that you want to open. FuncPlotter determines
the document format — XML or text
— by examining the first few bytes of the file.
The reporting of errors in a file differs according to the
file's format: files in text format receive more detailed
error reporting because it is assumed that they may have been
edited manually. (Files in XML format are assumed to have been
written by FuncPlotter.)
If a document in text format contains errors, a dialog box is
displayed in which the errors are listed. (Documents that are
saved by FuncPlotter should be free from errors, but there may be
errors in a document that has been edited manually.) The first
line of the error list is the pathname of the file that contains
the errors; the remaining lines list the first 20 errors in the
file, each prefaced by a line number. If the error is a syntax
error in an expression, the line number is followed by a number in
square brackets that denotes the position (ie, the character
index) of the error in the expression.
-
The Reload command is enabled when the current file has changed
since it was last opened or saved. If you select the Reload
command, the current file will be read again from storage,
replacing the modified file in FuncPlotter's buffer.
-
When you save a document with the Save command, the document is
written in the same format in which it was previously saved. If
you save a new document with the Save command, or if you
save a document with the Save As command, a file-selection dialog
is displayed in which you can choose not only the file to which
you want to save the document but also the document format — XML or text. The
document format is determined by the file type that you select in
the file selection dialog, and not by the filename suffix that you
specify. (For example, if you select a file named
a.txt and the file type "XML files", the
file is written in XML format.) If you select a file whose name
has no suffix, the suffix corresponding to the file type
(.xml or .txt) is automatically appended
to the filename. If the file type in the file selection dialog is
"All files", the default file type is
assumed.
If the general.saveFunctionColours
configuration property is set to Ask, you will be
asked whether you want to save the function colours in the
document each time you select either the Save or the Save As
command.
-
The Export Image command writes an image file of the current plot
panel in Portable Network Graphics (PNG) format. The command is
enabled when a document is open and the implementation of Java
supports the PNG image format. The colour resolution of the image
is 24 bits per pixel. The PNG format offers a high level of
compression for the sort of images that are exported by
FuncPlotter.
In the exported image, the margin of the plot, which includes the
scale markings, is drawn in the colour specified by the plot.colour.imageMargin
configuration property.
9.2 Edit menu
9.2.1 Undo/Redo
Edits to a document — changes that you make to a document's
functions, intervals or comment — can be undone and redone. The
number of edits that can be undone or redone is limited by the
available memory. The edits that are recorded include:
- adding or deleting a function;
- modifying a function, including its colour;
- changing the position of a function in the function list;
- scrolling or dragging the plot;
- zooming the plot;
- modifying the x or y intervals explicitly;
- modifying the document comment.
Changes to an interval in one dimension (eg, scrolling or zooming) are
merged if they occur within 0.5 seconds of each other.
If an edit is undone with the Undo command, it can subsequently be
restored with the Redo command provided that no other edits have been
made since it was undone. Saving a document clears the edits that can
be redone.
The Clear Undo/Redo Actions command clears the list of edits for the
current document. The command may be used to make more memory
available if a "Not enough memory" error occurs.
9.2.2 Comment
A document may contain a single document comment, which is
saved with the document. The Comment command displays a dialog box in
which the document comment can be viewed and edited. Any leading and
trailing space is removed from text that is entered in the dialog.
For documents that are saved in XML format, the document comment is
distinct from XML comments, which are not preserved in a document that
is opened and subsequently written by FuncPlotter. For documents that
are saved in text format, a document comment uses the general
convention for comments in that format, but in a particular way; see
Text format for details.
9.2.3 Reverse Order of Functions
This command reverses the order of the functions in the function list
of the current document.
9.2.4 Copy Intervals to Other Documents
The Copy Intervals to Other Documents command is enabled only when
more than one document is open. The purpose of this command is to
copy the x and y intervals of the current document
to some or all of the other open documents. A dialog box is displayed
in which the target documents — the documents whose intervals
you wish to set to those of the current document — can be
selected.
9.3 View menu
9.3.1 Grid
The Grid option controls whether a grid is drawn in the plot panel.
The command to toggle the grid also appears in the pop-up menu.
9.4 Options menu
9.4.1 Preferences
The Preferences command brings up a tabbed dialog box in which the
configuration properties of FuncPlotter can be edited. The
configuration properties are global; that is, they apply to all
documents. The properties on the various tabbed pages are described
below.
Some of the configuration properties in the Preferences dialog are
edited with a spinner — a graphical component that
consists of a text field adjacent to a pair of small buttons. The
value in the text field may be edited manually, or it may be
incremented and decremented by one of the following methods:
-
clicking on the small up/down buttons;
-
pressing the up/down arrow keys;
-
rotating the mouse wheel with the mouse cursor over the spinner when
the text field has keyboard focus (ie, the caret is displayed in the
field).
Using the last two methods, the amount by which the value is
incremented or decremented can be modified by holding down the Ctrl,
Shift or Ctrl+Shift keys, which correspond respectively to increments
of 10, 100 and 1000.
| General |
- Default file type
-
The default file-type property is used when a document's
file type is unknown (ie, when opening a document or saving a
new document): the file type in the file selection dialog box
is set to the default value. The file type may be changed in
the file selection dialog box each time a document is saved.
-
The default value is
XML.
|
- New document on startup
-
If you select
Yes, a new (ie, empty) document
will be displayed when FuncPlotter starts up.
-
The default value is
No.
|
- Save function colours in document
-
If you select
Yes, the colour of each function
will be included in the function definition when you save a
document. If you select No, the colour of each
function will be omitted from the function definition when you
save a document, and the functions will be assigned their
default colours when the document is opened. If you select
Ask, you will be asked whether you want to save
the function colours each time you save the document.
-
The default value is
Yes.
|
- Display UNIX-style pathnames
-
If you select Yes, pathnames are displayed in a
reduced "UNIX style" in some parts of the GUI. A
pathname is converted from its platform-specific form in two
steps:
-
If the pathname starts with the user's home directory,
the latter is replaced by "~".
-
The file-separator character ("\" on Windows
systems) is replaced by "/".
-
The default value is
No.
|
- Save location of main window
-
If you select
Yes, the location of the main
window on the screen will be saved to the configuration file
when you exit the application. The next time that FuncPlotter
is run, its main window will be positioned at the previously
saved location.
-
The default value is
No.
|
| Appearance |
- Look-and-feel
-
The look-and-feel (LAF) can be selected from a list of the
LAFs that are available on the current system.
-
The default value is the cross-platform LAF, currently called
Metal.
|
- Orientation by locale
-
The user interface has been prepared programatically for
locales that are associated with languages that have a
horizontal, right-to-left orientation (eg, Arabic, Hebrew).
This is intended to facilitate the translation of FuncPlotter
into right-to-left languages. However, as the text displayed
by FuncPlotter is currently hard-coded in English, using the
program in right-to-left locales would merely have the
undesirable effect of reversing the layout of components in
the GUI. This property controls whether the orientation of
components is dependent on locale. If you select
No, FuncPlotter ignores the locale when laying
out components (ie, the GUI is laid out from left to right).
-
The default value is
No.
|
- Text antialiasing
-
This determines the kind of antialiasing that is performed
when text is drawn in custom or partially customised
user-interface components (eg, in non-editable combo boxes).
Note that antialiasing is only a hint in Java; the
implementation is not required to perform the chosen
antialiasing.
-
This property has no effect on the antialiasing of text in
standard UI components, such as labels and menus, which is
determined by the Java implementation and the desktop setting
for text antialiasing (often referred to as "font
smoothing"). You can override the desktop setting with
the unsupported system property
awt.useSystemAAFontSettings.
-
The text antialiasing property can have the following values:
-
- Default
-
The desktop setting for text antialiasing (font smoothing)
is used, if the Java implementation recognises one;
otherwise, no antialiasing is performed.
- None
-
No antialiasing is performed.
- Standard
-
This selects pixel-oriented antialiasing rather than
subpixel antialiasing. It is suitable for non-LCD
displays.
- Subpixel, horizontal RGB
- Subpixel, horizontal BGR
- Subpixel, vertical RGB
- Subpixel, vertical BGR
-
These four options are intended to optimise the rendering
of text for LCD displays using subpixel antialiasing with
subpixels in the chosen arrangement. Selecting an option
that does not correspond to the actual arrangement of
subpixels in your LCD display may result in blurred text.
The most common arrangement of subpixels is horizontal
RGB.
-
The default value is
Default.
|
- Background colour
-
This is the colour that is used for the background of the main
window. (The background colour of the plot panel can be
configured separately.) If this property is not defined, the
default background colour for the current look-and-feel is
used instead. Although this property can be used in
application mode, it is intended primarily for use in applet
mode, to allow the FuncPlotter applet to have the same
background colour as the region of a HTML document in which it
is included.
-
In the Preferences dialog, the Background colour check box
determines whether this property is defined. If it is
defined, the colour can be specified from the colour selection
dialog.
-
By default, this property is undefined, which means that the
default background colour for panels in the current
look-and-feel will be used.
|
| Plot |
- Plot size
-
These are the dimensions of the plot (width × height) in
pixels.
-
The range of each dimension is 128 to 2048; the default
dimensions are 480 × 480.
|
- Show grid
-
If you select
Yes, a grid is displayed by default
in the plot panel. (The x and y axes are
always displayed.) The grid can be toggled on and off for
each document using the View > Grid command, which is also available
from the pop-up menu.
-
The default value is
Yes.
|
- Maximum number of fraction digits
-
This is the maximum number digits in the fractional part of
displayed numeric values — scale markings, cursor
coordinates and the endpoints of x and y
intervals. Values that have more than the maximum number of
digits in the fractional part are rounded away from zero; that
is, the digit immediately before any discarded digits is
incremented if the first discarded digit is greater than or
equal to 5. Thus, for example, if the maximum number of
fractional digits were 3, the value −3.6385 would be
rounded to −3.639, and 0.4475 would be rounded to 0.448.
-
The range of the value is 1 to 12; the default value is 5.
|
- Number of y-scale digits
-
This property determines the width of the left margin of the
plot in which the y scale is displayed. The width
allowed for the y-scale text is the total width of
the number of "0" (zero) characters specified by
this property.
-
The range of the value is 4 to 20; the default value is 8.
|
- Fixed-point exponent range
-
Numeric values — scale markings, cursor coordinates and
the endpoints of x and y intervals —
whose exponent lies between the (inclusive) limits of this
property are displayed in fixed-point format (eg,
−0.0123 and 279936.45). Values whose exponent lies
outside the limits are displayed in scientific notation (eg,
−1.23E−4 and 2.799364E7).
-
The range of each limit is −12 to 12; the default limits
are −3 and 6.
|
- Normalise scientific notation
-
This property determines whether numeric values — scale
markings, cursor coordinates and interval endpoints —
are normalised or denormalised when they are displayed in
scientific notation.
-
If you select
Yes, numeric values that are
displayed in scientific notation (ie, values whose exponent
lies outside the fixed-point exponent range) are normalised:
the radix point and exponent are adjusted so that there is
only one digit in the range 1..9 before the radix point.
-
If you select
No, numeric values that are
displayed in scientific notation are denormalised: the values
are displayed with a fixed exponent, which is the exponent of
the minimum of the absolute endpoints of the interval. For
example, if the x interval were [−5.0E8,
1.25E9], all x values would be displayed with the
exponent 8. (The upper endpoint would be displayed as
12.5E8.)
-
The default value is
Yes.
|
- Truncate x-scale text
-
If you select
Yes, the text of an
x-scale marking of the plot is truncated if it would
overlap the text of the previous marking. If you select
No, the text of an x-scale marking is
omitted if it is too wide. In either case, the full text is
displayed when the mouse cursor is moved over the region of
the truncated or omitted text.
-
The default value is
Yes.
|
- Plot colours
-
These are the colours of various elements of the plot panel.
|
| Function |
- Directory
-
This is the directory that is initially displayed by the file
selection dialog when opening or saving a document.
-
The default value is the directory specified by the Java
system property
user.home. If your system
supports it, you can drag and drop a directory object (eg,
from a file browser) on to the directory field, or copy a
directory object from a file browser to the clipboard, and
paste it into the field. The pathname specified in the
directory field can contain special
constructs for system properties, environment variables
and the user's home directory.
|
- Function list size
-
These are the dimensions of the viewable region of the list of
functions (columns × rows). The width of a column is
the width of a "0" (zero) in the main font. If the
number of viewable rows is less than the maximum (20), the
list has a vertical scroll bar.
-
The range of the number of columns is 8 to 80; the default
value is 32.
-
The range of the number of rows is 1 to 20; the default value
is 12.
|
- Default function colours
-
These are the default colours of functions in the function
list.
|
| Fonts |
-
These are the fonts that are used in FuncPlotter's
display. The Plot font is the font that is used for the scale
markings of the plot panel. Remember that font names may be
platform-dependent, so that a configuration that specifies
font names may not work across platforms.
-
The default values of all the font properties except for the
size of the plot font (10-point) are those of the default
fonts for the platform and look-and-feel. A default font size
is specified by leaving the size field empty (the minimum
position on the spinner). A default font is used if no font
name is specified in FuncPlotter's configuration or if the
named font is not available.
|
Some of the configuration properties will take effect when the
Preferences dialog is accepted (by closing it with OK); other
properties (eg, the look-and-feel and fonts) will not take effect
until the next time that FuncPlotter is run.
The configuration file is normally saved
automatically when FuncPlotter exits, if the configuration has
changed. The Save Configuration command in the Preferences dialog can
be used to save a configuration file explicitly.
9.4.2 Show Full Pathnames
The Show Full Pathnames option controls whether the full pathname of
the current document or only its filename is displayed in the title
bar of the main window.
9.5 Function-related commands
The buttons in the function panel, below the list of functions, issue
commands that relate to the list of functions:
- Add
-
Add a new function to the the list.
- Edit
-
Edit the currently selected function. When the function list has
keyboard focus, the expression of the selected function can be edited
by pressing Return or Enter.
- Copy
-
Copy the expression of the currently selected function to the system
clipboard. When the function list has keyboard focus, the expression
of the selected function can be copied to the system clipboard by
pressing Ctrl+C.
- Hide/Show
-
Hide or show the plot of the currently selected function.
- Delete
-
Delete the currently selected function. When the function list has
keyboard focus, the selected function can be deleted by pressing
Delete, which requires that you confirm the deletion, or Shift+Delete,
which deletes the function immediately.
- Clear
-
Delete all functions from the list.
There are two additional buttons in applet mode, for commands that
appear in the Edit menu in application mode:
- Undo
-
Undo the previous edit.
- Redo
-
Redo the next edit.
The Undo and Redo commands behave in the
same way as they do in application mode.
The function-related commands are also available from a pop-up menu,
which is activated in a system-dependent manner. (For example, on
Windows systems, the pop-up menu is displayed when the right mouse
button is released.)
9.5.1 Function dialog
The Add and Edit function commands cause a dialog box to be displayed in
which you can edit the expression for f(x) and select
the colour in which the function is plotted.
In the dialog, the colour selection button invokes a colour-selection
dialog. If the function list is not empty, the colours of the current
functions are displayed in small buttons beside the colour selection
button, to allow you to set a function's colour to the same colour
as another function.
The Copy, Paste and Clear buttons perform copy, paste and delete
operations on the entire contents of the expression field. The
Copy command copies the contents of the expression field to the
clipboard; the Paste command replaces the contents of the expression
field with text from the clipboard; the Clear command deletes the
contents of the expression field.
9.6 Opening files with drag-and-drop
If your system supports the feature, you can open files by dragging
them and dropping them onto the area of FuncPlotter's main window
below the menu bar. This is equivalent to opening the files with the
File > Open command. Multiple files can be opened in this way,
subject to the constraint that a maximum of 64 documents can be open
simultaneously in FuncPlotter.
10 Numeric values
[ Table of contents ]
FuncPlotter uses the double floating-point type of the Java
language for the numbers that are involved in evaluating and plotting
functions. The Java double type is based on the
double-precision (64-bit) floating-point format of the IEEE 754
standard, which has 53 bits of precision in the significand. This
precision is adequate for the purpose for which FuncPlotter is intended,
and operations on double-type numbers are relatively fast
on processors with a floating-point unit that implements the IEEE 754
double-precision format.
Even with the precision of a Java double, many of the
numeric values that are displayed by FuncPlotter will be approximations.
(Remember that the binary representation of decimal fractions is usually
inexact: the decimal fraction 0.1, for example, cannot be represented by
a binary fraction of finite length just as the fraction
1/3 cannot be represented by a decimal fraction of
finite length.)
Real numbers — or, rather, approximations to real numbers —
appear in three places in FuncPlotter's display:
-
the scale markings of the plot,
-
the coordinates of the pixel of the plot panel under the mouse cursor,
-
the lower and upper endpoints of the x and y
intervals.
For consistency, all three uses are subject to the same constraints and
are displayed in the same format, which can be controlled to a limited
extent by configuration properties.
The maximum precision (aka the number of "significant
figures") of displayed numbers is limited to 12 digits.
The maximum number of fraction digits (aka "decimal places")
in displayed numbers is determined by the plot.numFractionDigits
configuration property.
Numbers are displayed in one of two formats:
-
fixed-point format (eg, 23.456), in which the radix point is
placed before the first fraction digit;
-
scientific notation (eg, 2.345E−6), in which the
significand (the number before the "E") is
multiplied by 10 raised to the power of the exponent (the
integer after the "E"). If the first digit of the
significand is in the range "1".."9" and is
followed immediately by the radix point, the number is said to be
normalised. Thus, 6.24E−4 is normalised; 0.773E8 and
52.08E−6 are denormalised.
The format — fixed-point format or scientific notation — is
determined by the exponent of the number and the plot.fixedPointExponentRange
configuration property: if the exponent of the number lies within the
inclusive fixed-point exponent range, the number is displayed in
fixed-point format. (The exponent that is used in this determination is
the exponent of the number in scientific notation, normalised or
denormalised according to the plot.normaliseScientificNotation
configuration property.)
11 Expressions
[ Table of contents ]
An expression consists of operands and operators, optionally separated
by spaces. Subexpressions can be placed within parentheses,
"(" and ")", to override operator precedence or to
make an expression easier to read.
11.1 Operands
Simple operands are of three types:
|
variable
|
x
|
The independent variable.
|
|
symbolic constant
|
e
|
The base of natural logarithms.
|
pi
|
The ratio of the circumference of a circle to its diameter, π.
|
|
numeric constant
|
A string that is a valid representation of a decimal number
in the approximate range 10−308 to
10308, and composed only of the digits
"0".."9" and the characters "+",
"−", ".", "E", "e".
Numbers can be in exponential form; for example, 1.602 ×
10−19 would be 1.602E−19 or 1.602e−19.
|
11.2 Operators
There are two types of operator: unary and binary. Unary operators take
one operand; binary operators take two operands.
11.2.1 Unary operators
Unary operators use prefix notation: they always appear before
the operand in expressions, and they are right-associative. As well as
unary + and -, the unary operators include several common mathematical
functions. Because the unary operators have a higher precedence than
binary operators when evaluating expressions, there is no need to
enclose a simple operand of a mathematical function in parentheses. For
example, the expression sin2x can be written
sin x^2, though sin(x)^2 and (sin
x)^2 are acceptable — and less ambiguous —
equivalents.
|
Operator
|
Description
|
|
+
|
Unary plus
|
|
−
|
Unary minus
|
|
abs
|
Absolute value
|
|
acos
|
Inverse cosine, in the range [0, π]
|
|
acosh
|
Inverse hyperbolic cosine, in the range [0, ∞]
|
|
acot
|
Inverse cotangent, in the range [−π/2, π/2]
|
|
acsc
|
Inverse cosecant, in the range [−π/2, π/2]
|
|
asec
|
Inverse secant, in the range [0, π]
|
|
asin
|
Inverse sine, in the range [−π/2, π/2]
|
|
asinh
|
Inverse hyperbolic sine
|
|
atan
|
Inverse tangent, in the range ]−π/2, π/2[
|
|
atanh
|
Inverse hyperbolic tangent
|
|
ceil
|
Smallest integer value that is greater than or equal to the operand
|
|
cos
|
Cosine
|
|
cosh
|
Hyperbolic cosine
|
|
cot
|
Cotangent
|
|
csc
|
Cosecant
|
|
exp
|
e (base of natural logarithms) raised to the power of the operand
|
|
floor
|
Largest integer value that is less than or equal to the operand
|
|
lg
|
Logarithm, base 10
|
|
ln
|
Logarithm, base e (ie, natural logarithm)
|
|
round
|
Closest integer to the operand (1/2 is rounded up)
|
|
sec
|
Secant
|
|
sin
|
Sine
|
|
sinh
|
Hyperbolic sine
|
|
sqrt
|
Positive square root
|
|
tan
|
Tangent
|
|
tanh
|
Hyperbolic tangent
|
11.2.2 Binary operators
Binary operators use infix notation: they always appear between
their operands in expressions, and they are left-associative (eg,
1 − x − ln x is
evaluated as
(1 − x) − ln x).
The binary operators are the common arithmetic operators along with two
types of remainder operator and the exponentiation ("raised to the
power of") operator. Different precedence levels exist within the
set of binary operators.
|
Operator
|
Description
|
|
+
|
Addition
|
|
−
|
Subtraction
|
|
*
|
Multiplication
|
|
/
|
Division
|
|
%
|
Remainder (see below)
|
|
\
|
IEEE 754 remainder (see below)
|
|
^
|
operand1 raised to the power of operand2
|
The remainder operator, "%", is implemented in FuncPlotter by
means of the floating-point "%" operator of the Java language.
The operation, which is analogous to the integer remainder operation, is
defined by the Java
language specification 3e thus:
[T]he floating-point remainder r from the division of a
dividend n by a divisor d is defined by the
mathematical relation
r = n − (d×q)
where q is an integer that is negative only if
n/d is negative and positive only if is positive, and
whose magnitude is as large as possible without exceeding the magnitude
of the true mathematical quotient of n and d.
The IEEE 754 remainder operator, "\", performs a remainder
operation according to the IEEE 754 standard. It is implemented in
FuncPlotter by means of the java.lang.Math.IEEEremainder
method. The Java
API documentation describes the operation thus (with variables
renamed to be consistent with the definition of "%" above):
The remainder value is mathematically equal to
n − (d×q), where
q is the mathematical integer closest to the exact mathematical
value of the quotient n/d, and if two mathematical
integers are equally close to n/d, then q is
the integer that is even.
The Java
language specification 3e explains the difference between the
two remainder operations.
11.2.3 Operator precedence
The following table lists the precedence of operators in an expression,
with precedence decreasing from the top to the bottom of the table.
Operators on the same row have equal precedence. Parentheses override
operator precedence.
|
Unary operators
|
|
^
|
|
* / % \
|
|
+ −
|
12 Document formats
[ Table of contents ]
FuncPlotter supports two document formats, referred to as XML
and text, although they are both text (as opposed to binary)
formats. A document's format is also referred to as its file
type. Files of both types are expected to be encoded as UTF-8.
When a file is opened in FuncPlotter, the file type is determined by
examining the first five bytes of the file: if they are the UTF-8
character sequence <?xml, the file is parsed as XML;
otherwise, it is parsed as though it were in text format.
If you don't intend to edit a document manually, it is recommended
that you save it in XML format.
12.1 XML format
The XML format was introduced in version 1.2 in order to provide a
standard, interoperable format for FuncPlotter's documents.
Although it is possible to edit XML documents manually, it is assumed
that such documents were written by FuncPlotter, so the reporting of
any errors that are encountered on opening a document in XML format is
less detailed than the reporting of errors in a document in text
format.
The structure of the XML format is simple: the x and
y intervals are optional attributes of the
<functionList> root element, and the function
definitions are contained in zero or more
<function> elements that are children of the root
element. Each <function> element has an
expression attribute (required) and a colour
attribute (optional) whose forms correspond to the equivalent parts of
a function definition in documents in text format — see below.
The root element may contain a single <comment>
element for the document comment.
The DTD of documents in XML format can be found in the file
functionList.dtd, which is included in the FuncPlotter
distribution. The DTD is provided only for reference; it is not used
by FuncPlotter. Documents written by FuncPlotter in XML format do not
contain a document type declaration.
12.2 Text format
The original document format, now referred to as text format,
was designed to make it easy to create and edit sets of functions with
a text editor. A document consists of a series of statements. There
are two types of statement: an interval definition and a function
definition. Each statement must be on a separate line. Blank lines
are ignored. A document must contain no more than 20 function
definitions.
If a line contains a "#" character, any text from the
"#" to the end of the line is ignored. This can be used to
include comments in a document. There are two types of comment:
-
All comments that precede interval definitions and function
definitions are merged into a single document comment,
which can be edited from within
FuncPlotter and will be saved with the document. The number of
spaces between the "#" and the first non-space character
of the first line of a document comment is taken to be the indent
for the comment as a whole. Leading spaces up to the size of the
indent are removed from subsequent lines of the comment.
-
Comments that appear after the first interval definition or function
definition are termed line comments. They must be included
in a file by hand, and they are not preserved when FuncPlotter saves
the document. Line comments should therefore be used only to
annotate documents that will not be subsequently saved by
FuncPlotter.
An interval definition must begin with an interval identifier: the
"@" character followed by "x" or "y"
(lower or upper case). The interval identifier is followed by the
comma-separated lower and upper endpoints of the interval. Whitespace
is allowed on either side of the endpoint values. For example, the
line
@x -4.5, 3.2
specifies an x interval of [-4.5, 3.2].
An interval definition in a document is subject to the constraints
described in Numeric values. For example, if
the plot.numFractionDigits
configuration property has the value 3 and a document contains an
interval of [0.4521, 0.4523], the endpoints of the interval will be
deemed to be equal (ie, both are rounded to 0.452), which will result
in an error when the document is opened.
A function definition consists of two parts: an expression (required),
followed by a colour definition (optional). The expression is an expression for
f(x) as it would be entered in the Add Function or
Edit Function dialog box. If a colour is specified in the function
definition, it consists either of the RGB components of the colour in
the range 0..255, separated by commas, or of a "#" followed
by six hexadecimal-digit characters (HTML notation). The colour
definition is separated from the expression by a semi-colon. If the
colour definition is absent, the default
colour for that function is used instead. For example, the line
2*x^2 − 3*x + 1; 144, 0, 0
specifies the function
y = 2x2 − 3x + 1,
to be drawn in dark red, while the line
exp( 2*x ) − 3*x
specifies the function
y = e2x − 3x,
to be drawn in the default colour for the function at that particular
index.
When you save a document with the File > Save or File > Save As
commands, you are given the option of saving the colour definition
with each of the function definitions in the document according to the
policy outlined in the description of the Save
and Save As commands.
Appendix A: Special constructs in pathnames
[ Table of contents ]
Where indicated elsewhere in this document, pathname properties in
FuncPlotter can contain special constructs for system properties,
environment variables and the user's home directory. The special
constructs are expanded when the pathname is used.
- System properties
-
Java system properties (eg, the user's home directory,
user.home) are referenced by enclosing them between
"${" and "}"; that is, they must have the form
${<propertyKey>}.
-
• Example:
${user.home}/projects
- Environment variables
-
Environment variables are referenced by prefixing
"env." to them and enclosing them between
"${" and "}"; that is, they must have the form
${env.<variableName>}. The prefix for
environment variables can be changed by means of the
app.envPrefix property in the command line.
-
• Example:
${env.HOME}/projects
- User's home directory
-
A leading "~" in a pathname is expanded into the user's
home directory using the
user.home system property, which
is usually equivalent to the environment variable $HOME
on Linux/UNIX systems or %USERPROFILE% on Windows
systems.
-
• Example:
~/projects
On UNIX systems, the three examples given above all refer to the same
directory: the projects directory in the user's home
directory.
Remember that, if you use the ${<key>} form
from within a Linux/UNIX shell, you will have to escape the
"$" by prefixing "\" to it.
Appendix B: Configuration properties
[ Table of contents ]
The table below lists the properties that can be used in each of the
three configuration locations: applet parameters (in HTML), command-line
properties and configuration file. The property keys are given in
dot-separated pathname format.
When used in an applet parameter or a -D command-line
property, "app." must be prefixed to the property
key.
When used in a configuration file, the components of the property keys
become element names in the XML document hierarchy. (The
app prefix of the property key in applet parameters and
command-line properties corresponds to the root element of the XML
document.) The form of properties in a configuration file was changed
in version 2.1 of FuncPlotter. Configuration files in the old format
can be read, but files are written in the new format.
The <index> in a property key (eg,
function.colour) is a decimal-string representation of the
zero-based index of the property (eg, the colour of the third function
is function.colour2).
Any commas (",") or backslash characters ("\") in
the name of a font must be escaped by prefixing a "\"
character to them.
In the table below, the initial character of an italicised component of
a property value denotes its data type according to the following
convention:
| c |
colour: either r, g, b (decimal) or
#rrggbb (hex)
|
| f |
floating-point value |
| i |
integer |
| p |
platform-specific pathname, which may contain special
constructs
|
| s |
string |
| Property key |
Property value |
Applet |
System
property |
Config
file |
| configPath |
pPathname |
• |
• |
|
| general.defaultFileType |
xml | text |
|
• |
• |
| general.newDocumentOnStartup |
no | yes |
|
• |
• |
| general.saveFunctionColours |
no | yes | ask |
|
• |
• |
| general.showUnixPathnames |
no | yes |
|
• |
• |
| general.showFullPathnames |
no | yes |
|
• |
• |
| general.mainWindowLocation |
iX, iY
|
|
• |
• |
| appearance.lookAndFeel |
sName |
• |
• |
• |
| appearance.orientationByLocale |
no | yes |
• |
• |
• |
| appearance.textAntialiasing |
default | none | normal |
subpixelHRgb | subpixelHBgr |
subpixelVRgb | subpixelVBgr
|
• |
• |
• |
| appearance.backgroundColour |
cColour
|
• |
• |
• |
| plot.size |
iWidth, iHeight
|
• |
• |
• |
| plot.showGrid |
no | yes |
• |
• |
• |
| plot.numFractionDigits |
iNumDigits |
• |
• |
• |
| plot.numYScaleDigits |
iNumDigits |
• |
• |
• |
| plot.fixedPointExponentRange |
iLowerLimit, iUpperLimit
|
• |
• |
• |
| plot.normaliseScientificNotation |
no | yes |
• |
• |
• |
| plot.truncateXScaleText |
no | yes |
• |
• |
• |
| plot.colour.focusedBorder |
cColour
|
• |
• |
• |
| plot.colour.imageMargin |
cColour
|
• |
• |
• |
| plot.colour.background |
cColour
|
• |
• |
• |
| plot.colour.grid |
cColour
|
• |
• |
• |
| plot.colour.axis |
cColour
|
• |
• |
• |
| plot.colour.scale |
cColour
|
• |
• |
• |
| function.directory |
pPathname |
|
• |
• |
| function.listSize |
iNumColumns, iNumRows
|
• |
• |
• |
| function.colour<index> |
cColour
|
• |
• |
• |
| font.main |
sName, plain | bold | italic | boldItalic,
iSize
|
• |
• |
• |
| font.textField |
sName, plain | bold | italic | boldItalic,
iSize
|
• |
• |
• |
| font.comboBox |
sName, plain | bold | italic | boldItalic,
iSize
|
• |
• |
• |
| font.plot |
sName, plain | bold | italic | boldItalic,
iSize
|
• |
• |
• |
| startup.xInterval |
fLowerEndpoint, fUpperEndpoint
|
• |
|
|
| startup.yInterval |
fLowerEndpoint, fUpperEndpoint
|
• |
|
|
| startup.function<index> |
sExpression[;cColour] |
• |
|
|
Appendix C: Providing feedback about FuncPlotter
[ Table of contents ]
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. Follow the links labelled
Bugs or RFE / Feature requests.
When reporting a problem with FuncPlotter, please try to 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 (eg, suggestions for
improvement, errors in or omissions from this or other documents) 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.
