FuncPlotter 3.0 : Manual

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.
• The x and y coordinates at the mouse cursor are displayed when the mouse cursor is over the plot area.
• 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 ]

3  Contents of the distribution

[ Table of contents ]

The following files are included in the distribution:

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-config.xml, 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.2  Using FuncPlotter as an applet

Since FuncPlotter was first released, JavaScript in its various flavours has become established as the preferred way of embedding functionality such as FuncPlotter's in a web page. Because the use of FuncPlotter as an applet has become obsolete, no effort has been made to update this section for HTML5.

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. Microsoft 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, so you must either sacrifice (X)HTML conformity or have two separate pages, one for IE and one for browsers like Firefox 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.

Oracle'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 Oracle'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.configDir 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 fragment 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 denotes 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.configDir" 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>&lt;object&gt;</em>
  elements.<br/>
</object>

4.2.2  HTML fragment 2

This fragment 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 denotes 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.configDir" 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 version 7 or
  later installed.<br/>
</object>

4.2.3  HTML fragment 3

This fragment 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 known to be compatible with Internet Explorer and Firefox, and it may be compatible with other browsers.

<applet code="FuncPlotter"
        codebase="jar/"
        archive="funcPlotter.jar"
        width="937" height="537">
  <param name="app.configDir" 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>&lt;applet&gt;</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 recommended way to do this is with JavaScript. The file applet4.html shows how this can be done by including the script within an HTML document. In practice, 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 FuncPlotter's preferred dimensions. 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 collapsed. To discover the preferred dimensions of the FuncPlotter applet, run the applet: the preferred dimensions are displayed on the Java console and, if either dimension is too small, in an error message. Note that the preferred dimensions may change as a consequence 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 three-digit index of the function (eg, app.startup.function.002 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  Problems with keyboard focus

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, where 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 for requesting focus. The following (seemingly related) problems have been observed in the past, though not with combinations of recent versions of browsers and Java runtime environments:

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

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-config.xml, 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) 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 hash value of the entire FuncPlotter distribution against the values in the release notes on SourceForge.

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 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.3  Configuration file

The configuration file, which must be named funcPlotter-config.xml, 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 not recommended.) 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.

7  Document windows

[ Table of contents ]

8  The display

[ Table of contents ]

8.1  Plot panel

FuncPlotter's display consists of a main window divided into several panels. On the left side of the main window 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:

1. Click on the scroll buttons in the scroll/zoom panel.
2. Rotate the mouse wheel when the mouse cursor is over the plot panel.
   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.
3. Hold down the left mouse button and drag the mouse.
4. 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 denoted 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, (x_n, y_n) and (x_n+1, y_n+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 y_n = f(x_n) is an NaN, FuncPlotter does not draw a line segment between (x_n−1, y_n−1) and (x_n, y_n) or between (x_n, y_n) and (x_n+1, y_n+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 artifacts — unwanted 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 x_d is a value of x in the x interval of the plot at which there is an infinite discontinuity, {x_n} is the set of values of x for which f(x) is evaluated by FuncPlotter when plotting y = f(x), and x_nd is the member of {x_n} that is nearest to x_d, then the "cropped tail" artifact occurs when f(x_nd) lies within the y interval of the plot or when f(x_nd) is NaN. The severity of the problem is determined by how close x_nd is to x_d; 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 right of the display 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 with the Hide command, the colour sample is absent. If the function is obscured because another function has been highlighted with the Highlight command, the colour-sample box is empty (ie, only the border of the box is drawn.) 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 mouse, or by pressing Ctrl+Shift+Up or Ctrl+Shift+Down when the list has keyboard focus. The order of functions in the list can be reversed with the Edit > Reverse order of functions command, which is available only in application mode.

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.

Immediately below the list of functions is a group of buttons that can be used to issue function-related commands.

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 for 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⁻¹⁰⁰) and 1.0E100 (10¹⁰⁰) respectively.

Below the intervals panel is a panel containing scroll buttons, zoom buttons and drop-down lists 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 drop-down list beside each pair of zoom buttons.

8.5  Minus sign

In components of the main window and the function dialog that is displayed in response to the Add and Edit function commands, 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.

8.6  Function dialog

The Add and Edit function commands bring up a dialog box 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 commands 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  Commands

[ Table of contents ]

The commands that appear in the menu bar of FuncPlotter's main window are available only when FuncPlotter is run as an application.

9.5  Function-related commands

The function panel, below the list of functions, contains six buttons in application mode and eight buttons in applet mode. The buttons issue commands that relate to the list of functions. The 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  Add

This command brings up a dialog box in which a new function can be defined. The new function is added to the end of the function list.

9.5.2  Edit

This command brings up a dialog box in which the selected function can be edited. When the function list has keyboard focus, this command can be issued by pressing the Return key.

9.5.3  Copy

This command copies the expression of the currently selected function to the system clipboard. When the function list has keyboard focus, this command can be issued by pressing Ctrl+C.

9.5.4  View

This command brings up a small menu containing two check-box items: Highlight and Hide.

9.5.4.1  Highlight

This command toggles the highlighting of the selected function. The highlighting leaves the plot of the selected function unchanged but obscures the plots of all the other functions in the document. The way in which the plots are obscured depends on the function.obscuredColour configuration property: if the obscured colour is enabled, the plots are drawn in that colour, otherwise the plots are hidden. Only one function can be highlighted at a time; highlighting a function while another function is highlighted will switch off the highlighting of the first function. The command is enabled only if the document contains more than one function. It can also be issued by pressing Ctrl+Space when the function list has keyboard focus.

9.5.4.2  Hide

This command toggles the visibility of the plot of the selected function. It operates independently of any highlighting.

9.5.5  Delete

This command deletes the 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.

9.5.6  Clear

This command deletes all functions from the list.

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 ¹/₃ cannot be represented by a decimal fraction of finite length.)

Real numbers — or, more correctly, 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:

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 sin²x can be written sin x^2, though sin(x)^2 and (sin x)^2 are acceptable — and less ambiguous — equivalents.

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.

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 (Java SE 7 edition) thus:

[W]here neither an infinity, nor a zero, nor NaN is involved, the 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 n/d 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 and operators 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 (Java SE 7 edition) 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.

12  Document formats

[ Table of contents ]

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 and environment variables

Java system properties (eg, the user's home directory, user.home) and environment variables (eg, PATH) are referenced by enclosing them between '${' and '}'; that is, they must have the form ${<name>}. A Java system property takes precedence over an environment variable with the same name.

• Example: ${user.home}/projects

• Example: ${HOME}/projects

A Java system property can be specified by prefixing sys. to it.

• Example: ${sys.user.home}/projects

An environment variable can be specified by prefixing env. to it.

• 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

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.

When used in an applet parameter or a -D command-line property, app. must be prefixed to the property key (eg, app.general.mainWindowLocation).

The <index> of an indexed property key (eg, function.colour) is a three-digit decimal-string representation of the zero-based index of the property (eg, the colour of the third function is function.colour.002).

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:

Appendix C:  Providing feedback about FuncPlotter

[ Table of contents ]

The FuncPlotter project is hosted by SourceForge. You can submit bug reports, requests for enhancements (RFEs) and suggestions for improvements through the SourceForge website, but the mechanism for doing so may change depending on the facilities that SourceForge provides. For current information, please see the feedback page for Blank Aspect projects.

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:

• the version number of FuncPlotter,
• the name and version number of the operating system,
• the name and version number of the Java runtime environment,
• a description of the problem.

A Java stack trace, if one is available, would be helpful.