Subversion Repositories cheapmusic

This is the NEWS file for PHPlot, with release documentation.
The project web site is http://sourceforge.net/projects/phplot/
The project home page is http://phplot.sourceforge.net/
Refer the the ChangeLog file for detailed source changes.
See NEWS_part1.txt for older release documentation.
-----------------------------------------------------------------------------

2015-11-01 Release 6.2.0  

=== Overview:

This is the current stable release of PHPlot. This is the first release
that will work with the upcoming PHP-7. This release also adds two new plot
types.

The PHPlot Reference Manual has been updated to match this release.

=== Cautions, Important Notes, and Compatibility Issues:

PHP-7 deprecated use of older-style class constructor method names, where
the constructor name matches the class name.  The PHPlot class constructor
name in this release has been fixed to work with PHP-7. This release
also works with PHP-5.4, 5.5, and 5.6. However, there is a compatibility
issue with extended classes. This applies even if you are using PHP-5.

If you define a class which extends the PHPlot class, you must use this
syntax to call the PHPlot constructor from your class constructor:
     parent::__construct(...);  // Call parent class constructor
This syntax also works in previous releases of PHPlot. However, the
following syntax also worked in older releases, and will no longer work:
     $this->PHPlot(...);  // Do Not Use This to call parent class constructor
or:  parent::PHPlot(...); // Do Not Use This Either
You must use the correct syntax parent::__construct() even if using PHP-5.

If you are using PHP-7 with PHPlot, here are a few other items to be aware of.
(Some of these affected the PHPlot test suite.)

+ PHPlot uses is_numeric() to check for missing points in the data array.
Starting with PHP-7, hexadecimal strings are no longer considered numeric.
This means if your data array contains the string "0x10", for example, PHPlot
will consider that to be the number 16 when using PHP-5.x, but will treat it
as a missing point with PHP-7. (Unquoted hexadecimal values are still numbers.)

+ PHP-7 no longer allows multiple function parameters with the same name.
A typical case which fails in PHP-7 is:
       function myfunction($s, $unused, $unused);  // Fails in PHP-7
This broke some PHPlot Test Suite scripts that implemented PHPlot callbacks
with unused parameters.

+ New objects cannot be assigned by reference. Very old versions of the
PHPlot Reference Manual had this syntax (and there may still be some old
versions out there):
        $plot =& new PHPlot(600, 400);  // Do not use &

+ Division by zero no longer results in E_WARNING, but you end up with one
of the special float values +INF, -INF, or NAN instead.


=== Bugs Fixed in 6.2.0:

Fixed bug #170 "replace eval() ...":
This was a request to remove use of eval() from SetDashedStyle(), because
eval() makes people nervous about security, and is not supported by some
Virtual Machines. Removed eval() by using a string template instead of a
code string for the dashed line pattern. There are no changes in usage or
behavior.

Fixed bug #172 "Fixes for PHP7":
This release now works with PHP-7 (currently pre-release). The constructor
name was changed; there were no problems with the rest of the code.
(Although several scripts in the PHPlot Test Suite also had to be fixed.)
Any class that extends PHPlot must now use the correct syntax to call the
parent constructor: parent::__construct(...). If they used the old syntax
$this->PHPlot(...) they will not work (even with PHP-5.x).


=== New features in 6.2.0:

Feature Request #55 "Method documentation in PHPDoc format":
PHPlot now uses "phpdoc"-style comments in the code, which apparently is
supported by some editors/IDEs. Note that the PHPlot Reference Manual does
currently make use of these comments.

Feature Request #56 "Hidden Y values when zero":
The request was for a way to hide Y label values when zero, but the
implementation is much more general. When using 'printf' label formatting
type, you can now specify 1, 2, or 3 separate format strings. These are
applied in the same way spreadsheets support cell format strings: which
format is used depends on the sign of the value.

Feature Request #57 "squarefilled plot type":
Two new plot types are added: 'squaredarea' and 'stackedsquaredarea'.
These are like area and stackedarea, but the edges are stepped like
'squared' plots.

Feature Request #58 "Data borders for area plot types":
After data borders support was added to the two new plot types 'squaredarea'
and 'stackedsquaredarea', this was extended to the existing, similar plot
types 'area' and 'stackedarea'. Data borders are off by default for all 4
plot types.

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

2013-05-11 Release 6.1.0

=== Overview:

This is the current stable release of PHPlot. This release includes two new
plot type features (which were not completed in time to make it into
PHPlot-6.0.0).

The PHPlot Reference Manual has been updated to match this release.


=== Cautions, Important Notes, and Compatibility Issues:

There are no new compatibility issues in this release. However, if
upgrading from PHPlot-5.8.0 or older, please read the Cautions, Important
Notes, and Compatibility Issues from the PHPlot-6.0.0 release. Everything
there is still applicable.


=== Bugs Fixed in 6.1.0:

(none)


=== New features in 6.1.0:

Feature Request #47 "Extend horizontal plots to more types":
This feature request was mostly implemented in PHPlot-6.0.0, except for
horizontal error plots, which are now implemented. A new data type
'data-data-yx-error' is used for horizontal error plots of type lines,
points, and linepoints.

Feature request #52 "Box Plots":
A new plot type 'boxes' is added. This produces a Box Plot, which is used
to present a 5-number statistical summary of a data set.


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

2013-04-03 Release 6.0.0

=== Overview:

This is the current stable release of PHPlot. This release includes a
significant rewrite how PHPlot automatically calculates the plot area range
and tick increments from the data points. A number of new features and bug
fixes are also included.

The PHPlot Reference Manual has been updated to match this release. A
previously-experimental feature to help create HTML image maps is now
fully documented in the manual.


=== Cautions, Important Notes, and Compatibility Issues:

There are some important compatibility issues you need to be aware of
before upgrading to PHPlot-6.0.0 from any previous version. Many scripts
will produce different-looking plots with PHPlot-6.0.0 compared to earlier
versions. This is mostly due to changes in the automatic plot range and
tick increment calculations. Also, some scripts may fail, if they access
PHPlot class internal variables (properties) which have been changed to
have 'protected' visibility. See the details below.

+ Plot range calculations changed

PHPlot-6.0.0 uses a completely new method to calculate each of the 4 limits
of the plot area which are not defined using SetPlotAreaWorld(). As a
result, most plots that don't use SetPlotAreaWorld() with all 4 coordinates
given will look different under PHPlot-6.0.0. The two most notable changes
are that PHPlot-6.0.0 will usually stretch the range to include zero (if
the range does not already include zero), and under most conditions will
ensure that the X axis and Y axis both start and end at a tick mark position
(even if tick marks and labels are not visible). See bug #101 below.

+ Tick increment calculations changed

PHPlot-6.0.0 uses a completely new method to calculate tick increments
along the X axis and Y axis. This only occurs if the tick increments have
not been set using SetXTickIncrement() or SetNumXTicks() for X, and
SetYTickIncrement() or SetNumXTicks() for Y. If you let PHPlot calculate
the tick increments, your plot will likely have fewer or more tick
intervals than before, and the tick increment will be different. In
general, PHPlot-6.0.0 makes much better choices for tick increment.
See bug #132 below.

+ Class variable visibility changed

Most PHPlot class variables now have 'protected' visibility, so they are no
longer accessible from scripts that use the class. If your script directly
accesses PHPlot class variables - other than those documented in the manual
for 'tuning' - your script will not work with PHPlot-6.0.0. This change was
necessary because some internal class variables change in each PHPlot release,
and it is impossible to maintain compatibility with direct access to all these
class variables. If your script breaks because of variable visibility changes,
please: (1) see if you can use a public PHPlot class function instead, or
(2) post a message to the PHPlot help forum explaining why you need access to
a particular class variable.

+ SetPlotAreaWorld() now validates arguments

Starting with PHPlot-6.0.0, the SetPlotAreaWorld() function checks non-NULL
arguments for validity. For both X and Y, it is required that min < max if
both are specified. If you have a script that calls SetPlotAreaWorld() with
max <= min for either X or Y, that script will now fail. On the other hand,
some valid cases where you specify only one end of a range would previously
fail and now work.

+ SetRGBArray() now validates argument

If you use SetRGBArray() to load a custom color map but pass an invalid
argument (not an array or one of the known keywords), PHPlot will now fail
with an error message. In previous releases, a default black/white color
map was loaded in that case, with no error reported.

+ Removed order dependency: number of ticks and tick increment

If you want to control the tick increments (rather than letting PHPlot
calculate them), you should set either the number of ticks (SetNumXTicks(),
SetNumYTicks()) or the tick increment (SetXTickIncrement(),
SetYTickIncrement()), but not both, for each axis.  If you do set both,
PHPlot-5.8.0 and earlier will use the last setting you made, and ignore the
other.  PHPlot-6.0.0 gives priority to the tick increment setting and
ignores the number of ticks, regardless of the order. (The new behavior is
consistent with the PHPlot design goal that you can use the various Set*()
functions in any order and get the same plot.)


=== Bugs Fixed in 6.0.0:

Fixed bug #101 Fix automatic Y range calculations":
PHPlot now calculates the Y (and X) ranges using a completely different
method, which is described in the manual. There are new functions to 'tune'
the algorithm used, and of course you can still set the range limits manually.
In most cases, PHPlot now makes much better choices for the plot range limits.

Fixed bug #132 "Improve tick interval calculations":
PHPlot now by default picks a tick increment which is 1, 2, or 5 times a
power of 10, for much more 'natural' results. There are alternate
algorithms for selecting a 'binary' (power of 2) or date/time-based tick
increment instead. Rather than simply dividing the plot range by 10, PHPlot
now selects a tick increment based on the above requirement and which
results in at least 8 (by default) tick intervals.  Of course, you can
still specify the tick increment(s) directly.

Fixed bug #164 "Calculated defaults applied to subsequent plots":
This has been fixed for the cases of grid visibility, X data label angle,
and label format. A new bug #168 was written for a remaining issue with
label position defaults. This only apples when creating multiple plots on a
single image (overlay or side-by-side).

Fixed bug #165 "Missing axis labels on some empty plots":
In some cases, X axis labels would be absent for a plot with an empty data
array. PHPlot will now draw the axis labels even when the data array is empty.

Fixed bug #166 "Legend, UsePointShapes, and shape='none'":
PHPlot will now fall back to using a point marker in the legend when doing
a linepoints plot with a dataset using 'none' as the point shape (rather
than doing no marker at all). This only applies with SetLegendUseShapes(True).

Fixed bug #167 "Fails to find a default font on Ubuntu":
Ubuntu (via Debian) changed the installation path for the TrueType font
that PHPlot used as a default, causing font selection to fail.  The new
font installation path has been added to the search list, and now PHPlot
can find the default TrueType font on Ubuntu.


=== New features in 6.0.0:

Feature request #29 "Finer control over plot element colors":
This was an open-ended feature request that is partially implemented and
now closed. New functions were added to control element colors. (Some other
functions were added in previous releases.) In PHPlot-6.0.0, these functions
were added: SetLegendBgColor() for legend background color;
SetLegendTextColor() for legend text color, and functions for pie chart
border colors (see feature request #46 below).

Feature request #45 "Control pie chart start angle":
Implemented with new functions SetPieStartAngle() and SetPieDirection().
The angle for the first segment, and the direction (clockwise or
counter-clockwise) can now be set for pie charts.

Feature request #46 "Control pie chart borders":
Implemented with new functions SetDrawPieBorders() and SetPieBorderColor().
Pie segment borders can now be on (default for unshaded) or off (default for
shaded), and the color can be set independent of other elements.

Feature request #47 "Extend horizontal plots to more types":
This is partially implemented. Horizontal lines, linepoints, and points plots
are now implemented. Error plot versions of those horizontal plot types are
not yet implemented, but will probably be in the next release 6.1.0 (with
the introduction of a new data type).

   Note: In implementing feature request #47, the code for 'error' and
   'non-error' versions of the 3 plot types above were merged. A side effect
   of this is that data value labels (the labels within the plot area,
   identifying the data value at each point) now work for error plots, if
   enabled.  However, the default label position at 90 degrees will be crossed
   by the positive error bar. To avoid this, you can use the tuning variable
   data_value_label_angle; for example setting it to 45 degrees.

Feature request #50 "Control legend colorbox borders":
Implemented with new function SetLegendColorboxBorders().  There are now 3
choices for the borders around color boxes in the legend: 1) use the 'text'
color (the default, and compatible with PHPlot-5.8.0 and older); 2) use
data border colors; and 3) disable the borders.

  Note: Along with the implementation of feature request #50, a new function
  SetDrawDataBorders() was added to control drawing the data borders on bars
  and stackedbars plots. This supports having the same style (borders with
  matching color, or no borders) on both the legend color boxes and the data
  bars. The default is backward compatible: borders on unshaded plots, and
  no borders on shaded plots.

Feature request #51 "Lines instead of colorboxes in legend":
Implemented with existing function SetLegendUseShapes().  PHPlot now has
the option of showing short line segments (with correct color and width) in
the legend, rather than color boxes. This applies to lines and squared
plots only.

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

2012-04-06 Release 5.8.0

=== Overview:

This is the current stable release of PHPlot. This release adds several new
features, including the ability to generate "streaming plots" - a video
stream showing updated plot data.

The PHPlot Reference Manual has been updated to match this release.


=== Cautions, Important Notes, and Compatibility Issues:

There are no known compatibility issues in upgrading from PHPlot-5.7.0 to
this release. For issues with previous releases, see below in this file.


=== Bugs Fixed in 5.8.0:

Fix bug #3506408 "Data Label Lines vs new plot types":
Data label lines do work with bubble plots. This is now documented. Data
label lines did not work well with OHLC plot types. This was never documented
to work, and is now disabled.


=== New features in 5.8.0:

Feature request #3488042 "Display only some data value labels":
Custom label formatting functions now have access to the data point row and
column for data value labels, and to the row for axis data labels. You can
now filter or modify labels based on their position in the data array.
Documentation was updated.

Feature request #3501500 "Looping plot section (updating plot data)":
PHPlot can now produce "streaming plots", with updating data presented as a
Motion-JPEG stream. Documentation has been added to the reference manual.

Feature request #3515519 "Support object serialize/unserialize":
You can now serialize and unserialize a PHPlot object, subject to some
minor restrictions. Details are in the PHPlot Reference Manual.

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

2012-02-25 Release 5.7.0

=== Overview:

This is the current stable release of PHPlot. This release includes several
bug fixes, new color controls for labels, a new feature for application-level
error handling, and an experimental feature for creating plot image maps.

The PHPlot reference manual has been updated to match this release.


=== Cautions, Important Notes, and Compatibility Issues:

This release includes a change in how the color is set for data value
labels. (These are the labels inside the plot area that identify the tops
of bars, for example.) This can change the color of some labels. See the
bug report "Wrong color for data value labels" below.

This release reverts a change from PHPlot-5.4.0 to stackedbars plots. It
affects plots with stacked bar segments of size 0 that are at the top or
end of a stack. Starting in PHPlot-5.4.0, a zero-size segment at the top or
end would result in a color 'cap' on the bar stack, using the data color of
the zero-size segment. In PHPlot-5.7.0 this has been fixed. This will
change the appearance of some stackedbars plots.  See the bug report "Top
dropshadow [sic] of stacked bars..."


=== Bugs Fixed in 5.7.0:


#3396931 "Top dropshadow of stacked bars is always the same color":
  PHPlot will no longer draw a color 'cap' at the top or end of a bar stack
  if the last segment has a 0 value. (The term 'dropshadow' isn't correct.)
  Drawing the color for zero-size segments started in PHPlot-5.4.0 as part of
  the fix for bug #3296884, but the behavior was unexpected, so it was reverted.
  In general, PHPlot will now ignore segments with size 0, and if a stack
  contains all 0 values it will not be drawn. (The exception is if the axis is
  moved.)

#3488064 "Pie label failures in locales with comma decimal":
  Two work-arounds are implemented for what is essentially a PHP problem with
  locales that use something other than a period (typically comma) for the
  decimal separator.  When formatting labels as type 'data', PHPlot loads the
  locale settings to get the separator characters, but now it resets ('unloads')
  the settings afterwards. This helps avoid an error seen in PHPlot-5.6.0 with
  pie chart labels, where an incidental conversion of the label to a string
  resulted in use of the comma separator, followed by PHP failing to convert
  the number back to floating point because of the comma.  The second
  work-around is to avoid the conversion to string, in the case where the pie
  label has a single value. Together, these work-arounds should prevent the
  problem, but this is an imperfect fix.

#3486834 "Wrong color for data value labels":
  PHPlot was using the 'title' color (SetTitleColor()) for data value labels,
  which was wrong, as the title color is for the 3 plot title strings. PHPlot
  will now use the general text color (SetTextColor()) for data value labels,
  same as tick labels and axis data labels. This will change the appearance
  of some plots. In order to help with the compatibility issue, 4 new
  functions are introduced to control the colors of individual label types:
  SetTickLabelColor(), SetPieLabelColor(), SetDataLabelColor(), and
  SetDataValueLabelColor(). The defaults have been set up to be compatible
  (except for data value labels). Details are in the PHPlot Reference Manual.

=== New features in 5.7.0:

#3442041 "Provide data for generating image maps":
  An experimental feature has been added to allow a callback function to
  process the coordinates of individual plotted data points. This is most
  useful for generating an HTML image map for the plot. Refer to the text
  file Imagemaps.txt included in the PHPlot release for details. Caution:
  This is an experimental feature. It is subject to change, and not yet
  documented in the reference manual.

#3481195 "Custom message image":
  A new function DrawMessage() has been implement for special cases where you
  need to display an image containing a message, rather than a plot. This
  extends the PHPlot error reporting mechanism, and is intended for
  application-level errors. More information and an example can be found
  in the PHPlot Reference Manual.


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

2012-01-02 Release 5.6.0

=== Overview:

This is the current stable release of PHPlot. This release includes
significant changes to pie charts. There are new ways to label pie charts,
and PHPlot does a better job calculating the size and positioning the labels.

The PHPlot reference manual has been updated to match this release.


=== Cautions, Important Notes, and Compatibility Issues:

Pie charts will change appearance when you upgrade to PHPlot-5.6.0 from any
previous release. This is due to changes resulting from bug #3403297,
described below. You may notice these changes:

1. The pie chart itself will usually be drawn larger, taking up more of
   the image. This may result in interference with a plot legend.

2. Pie chart labels will be closer to the edge of the pie, if you are letting
   the label positions default. If you are using SetLabelScalePosition() to
   set the label positions, the results may vary even more.

3. Text alignment on pie chart labels will change.

4. World Coordinates are now undefined with pie charts.

If you are producing pie charts with PHPlot, you should review the output
of your scripts before using PHPlot-5.6.0 in production. If the output is
not acceptable, one or more of these steps might help:

1. If pie charts are too large, and/or interfere with a legend, try moving the
   legend. Alternatively, use SetPlotAreaPixels() or SetMarginsPixels() to
   limit the plot area.  Note, however, that starting in this release PHPlot
   sizes the pie so the labels fit inside the plot area too. You can control
   this with SetPieAutoSize().

2.  If you want labels positioned just outside the pie chart, do not call
    SetLabelScalePosition(), or set the value to the default 0.5. If you want
    labels just inside the pie, use 0.49. If you want labels to be about
    half-way inside the pie, use 0.25. (In previous releases, PHPlot multiple
    the label scale position by 1.2 before using it to position the labels,
    but this was not documented.)

3.  Your pie chart script will report errors if you use GetDeviceXY(),
    SetLegendWorld(), or SetLegendPosition(...,..., 'world'). This is because
    these functions require world coordinates, and world coordinates are not
    defined for pie charts. (Previous releases did define a world coordinate
    space for pie charts, but the values were meaningless.)



=== Bugs Fixed in 5.6.0:

#3403297 Pie chart sizing and label issues:
In addition to the fixes listed here, new features were added as a result
of this bug fix (see New features below).

+ Use both width and height of the pie when calculating its maximum size.
  (The bug was that the pie diameter would be sized to fit in the smaller
  of the image width and height. But a shaded pie is oval, so when the width
  if the pie was sized to the height of the image, the pie was too small.)

+ Fixed the text alignment of pie labels so they extend more naturally
  away from the pie chart (if outside the pie). (Don't just use center/center
  alignment for all labels.)

+ Do not multiply the label scale position by 1.2 in the hope that this will
  prevent labels from overlapping the pie. Use the label scale position
  as intended, and take other measures to prevent label overlap (such as
  fixing the text alignment).

+ Label positions along the bottom of the pie are now adjusted to account for
  the pie shading depth.

+ Plot area borders now work with pie charts. Use SetPlotBorderType() to
  enable them. The default is not to draw borders.

=== New features in 5.6.0:

A number of new features were added as a result of bug #3403297, described
above. The new features are:
+ Use the new function SetPieLabelType() to select the type of pie labels
  to be displayed. Labels can show segment percentages, segment values,
  string labels, or any other value using a custom function.

+ SetPieLabelType() also allows control over formatting of pie labels,
  similar to the way X and Y tick and data labels can be formatted.

+ Plot labels can be suppressed with SetLabelScalePosition(0).

+ The aspect ratio of shaded pies can be controlled with a tuning variable
  $pie_diam_factor. The default remains 0.5, making the pie height equal to
  half its width.



#413925 Table of values:
This very old feature request was implemented by adding a new script to the
"contrib" directory.  The data_table.php script contains a function to draw
a simple table of values on a PHPlot image. Examples are provided.


-----------------------------------------------------------------------------
For older releases, see NEWS_part1.txt