updated barchart doc

lib/jkqtplotter/graphs/jkqtpbarchart.cpp

@@ -48,7 +48,7 @@ JKQTPBarVerticalGraph::JKQTPBarVerticalGraph(JKQTPlotter* parent):
 
 void JKQTPBarVerticalGraph::draw(JKQTPEnhancedPainter& painter) {
 #ifdef JKQTBP_AUTOTIMER
-    JKQTPAutoOutputTimer jkaaot("JKQTPBarHorizontalGraph::draw");
+    JKQTPAutoOutputTimer jkaaot("JKQTPBarVerticalGraph::draw");
 #endif
     if (parent==nullptr) return;
     const JKQTPDatastore* datastore=parent->getDatastore();

lib/jkqtplotter/graphs/jkqtpbarchart.h

@@ -32,66 +32,21 @@
 #include "jkqtplotter/graphs/jkqtpbarchartbase.h"
 
 
-/*! \brief This implements a vertical bar graph with bars between \f$ y=\mbox{baseline} \f$ and \f$ y=f(x) \f$
+/** \brief This implements a vertical bar graph with bars between \f$ y=\mbox{baseline} \f$ and \f$ y=f(x) \f$
-    \ingroup jkqtplotter_barcharts
+ *  \ingroup jkqtplotter_barcharts
-
+ *
-    This class plots a bargraph. This image explains the parameters:
+ *
-
+ *  This class draws vertical bargraphs. The basic properties are defined and documented with JKQTPBarGraphBase .
-    \image html bargraph_basics.png
+ *
-
+ *  The a horizontal is defined by a series of datapoints \c (x,y=f(x)) .
-    By default the shift parameter is, so the bar is centered at the x-value. The width is 0.9,
+ *  Bars are then drawn fromm a baseline (often \c =0 ) to the value \c y=f(x) at each position \c x .
-    so adjacent bars are plotted with a small distance between them. It is possible to use these two parameters
+ *  Thus the class is derived from JKQTPXYBaselineGraph, which provides a baseline as well as columns for \c x and \c y values.
-    to plot multiple bars for every x-value, by having on JKQTPSpecialLineHorizontalGraph object per
+ *
-    set of bars that belong together. For example for three bars per x-value one would set:
+ *  \image html JKQTPBarVerticalGraph.png
-    \verbatim
+ *
-          width=0.3
+ *  \see \ref JKQTPlotterBarcharts, jkqtpstatAddHHistogram1D(), jkqtpstatAddHHistogram1DAutoranged()
-          shift=-0.3 / 0 / +0.3
+ *
-    \endverbatim
+ *
-    This results in a bargraph, as shown here:
-
-    \image html JKQTPBarVerticalGraph.png
-
-
-    You can also set JKQTPBarGraphBase::FillMode::TwoColorFilling, which uses different fill styles for bars above and below
-    the baseline of the graph:
-
-    \image html JKQTPBarVerticalGraphTwoColorFilling.png
-
-   If you use JKQTPBarGraphBase::FillMode::FunctorFilling you can specify the fill style by a functor, e.g.
-   \code
-     graph->setFillMode(JKQTPBarGraphBase::FillMode::FunctorFilling);
-     graph->setFillBrushFunctor(
-       [](double key, double value) {
-         return QBrush(QColor::fromHsvF(key/12.0, 1.0, 1.0));
-       }
-     );
-   \endcode
-
-   The result may look like this:
-
-   \image html JKQTPBarVerticalGraphFunctorFilling.png
-
-
-   You can also completely customize the drawing by defining a custom draw functor:
-   \code
-     graph->setCustomDrawingFunctor(
-       [](JKQTPEnhancedPainter& painter, const QRectF& bar_px, const QPointF& datapoint, Qt::Orientation orientation, JKQTPBarGraphBase* graph) {
-         // draw the bar (if required), pen and brush are already set properly
-         painter.drawRect(bar_px);
-         // now we can add some decoration or replace the instruction above:
-         // ........
-       }
-     );
-     // enable usage of cutom draw functor
-     graph->setUseCustomDrawFunctor(true);
-   \endcode
-
-   See \ref JKQTPlotterBarchartsCustomDrawFunctor for a detailed example.
-   The result may look like this:
-
-   \image html JKQTPBarVerticalGraphCustomDrawFunctor.png
-
-   \see JKQTPBarHorizontalGraph, \ref JKQTPlotterBarcharts, jkqtpstatAddHHistogram1D(), jkqtpstatAddHHistogram1DAutoranged()
  */
 class JKQTPLOTTER_LIB_EXPORT JKQTPBarVerticalGraph: public JKQTPBarGraphBase {
         Q_OBJECT
@@ -123,9 +78,13 @@ class JKQTPLOTTER_LIB_EXPORT JKQTPBarVerticalGraph: public JKQTPBarGraphBase {
  *         and error indicator
  *  \ingroup jkqtplotter_barcharts
  *
- *  This works much the same as JKQTPBarHorizontalGraph. Here is an example output:
+ *  This works much the same as JKQTPBarHorizontalGraph, but also draws error indicators.
+ *  Here is an example output:
+ *
  *  \image html JKQTPBarVerticalErrorGraph.png
  *
+ *  Error indicators are defined and styled with the functions from JKQTPYGraphErrors .
+ *
  * \see jkqtpstatAddYErrorBarGraph(), JKQTPBarVerticalGraph, \ref JKQTPlotterBarcharts
  */
 class JKQTPLOTTER_LIB_EXPORT JKQTPBarVerticalErrorGraph: public JKQTPBarVerticalGraph, public JKQTPYGraphErrors {
@@ -178,52 +137,20 @@ class JKQTPLOTTER_LIB_EXPORT JKQTPBarVerticalErrorGraph: public JKQTPBarVertical
 
 
 
-/*! \brief This implements a horizontal bar graph with bars between \f$ x=\mbox{baseline} \f$ and \f$ x=f(y) \f$
+/** \brief This implements a horizontal bar graph with bars between \f$ x=\mbox{baseline} \f$ and \f$ x=f(y) \f$
-    \ingroup jkqtplotter_barcharts
+ *  \ingroup jkqtplotter_barcharts
-
+ *
-    This works much the same as JKQTPBarHorizontalGraph. Here is an example output:
+ *  This class draws horizontal bargraphs. The basic properties are defined and documented with JKQTPBarGraphBase .
-
+ *
-    \image html JKQTPBarHorizontalGraph.png
+ *  The a horizontal is defined by a series of datapoints \c (y,x=f(y)) .
-
+ *  Bars are then drawn fromm a baseline (often \c =0 ) to the value \c x=f(y) at each position \c y.
-    You can also set JKQTPBarGraphBase::FillMode::TwoColorFilling, which uses different fill styles for bars above and below
+ *  Thus the class is derived from JKQTPXYBaselineGraph, which provides a baseline as well as columns for \c x and \c y values.
-    the baseline of the graph:
+ *
-
+ *  \image html JKQTPBarHorizontalGraph.png
-    \image html JKQTPBarHorizontalGraphTwoColorFilling.png
+ *
-
+ *  \see \ref JKQTPlotterBarcharts, jkqtpstatAddVHistogram1D(), jkqtpstatAddVHistogram1DAutoranged()
-   If you use JKQTPBarGraphBase::FillMode::FunctorFilling you can specify the fill style by a functor, e.g.
+ *
-   \code
+ *
-     graph->setFillMode(JKQTPBarGraphBase::FillMode::FunctorFilling);
-     graph->setFillBrushFunctor(
-       [](double key, double value) {
-         return QBrush(QColor::fromHsvF(key/12.0, 1.0, 1.0));
-       }
-     );
-   \endcode
-
-   The result may look like this:
-
-   \image html JKQTPBarHorizontalGraphFunctorFilling.png
-
-   You can also completely customize the drawing by defining a custom draw functor:
-   \code
-     graph->setCustomDrawingFunctor(
-       [](JKQTPEnhancedPainter& painter, const QRectF& bar_px, const QPointF& datapoint, Qt::Orientation orientation, JKQTPBarGraphBase* graph) {
-         // draw the bar (if required), pen and brush are already set properly
-         painter.drawRect(bar_px);
-         // now we can add some decoration or replace the instruction above:
-         // ........
-       }
-     );
-     // enable usage of cutom draw functor
-     graph->setUseCustomDrawFunctor(true);
-   \endcode
-
-   See \ref JKQTPlotterBarchartsCustomDrawFunctor for a detailed example.
-   The result may look like this:
-
-   \image html JKQTPBarHorizontalGraphCustomDrawFunctor.png
-
-    \see \ref JKQTPlotterBarcharts, jkqtpstatAddVHistogram1D(), jkqtpstatAddVHistogram1DAutoranged()
  */
 class JKQTPLOTTER_LIB_EXPORT JKQTPBarHorizontalGraph: public JKQTPBarGraphBase {
         Q_OBJECT
@@ -262,9 +189,13 @@ class JKQTPLOTTER_LIB_EXPORT JKQTPBarHorizontalGraph: public JKQTPBarGraphBase {
  *         and error indicator
  *  \ingroup jkqtplotter_barcharts
  *
- *  This works much the same as JKQTPBarHorizontalGraph. Here is an example output:
+ *  This works much the same as JKQTPBarHorizontalGraph, but also draws error indicators.
+ *  Here is an example output:
+ *
  *  \image html JKQTPBarHorizontalErrorGraph.png
  *
+ * Error indicators are defined and styled by functions from JKQTPXGraphErrors.
+ *
  * \see jkqtpstatAddXErrorBarGraph(), JKQTPBarHorizontalGraph, \ref JKQTPlotterBarcharts
  *
  */

lib/jkqtplotter/graphs/jkqtpbarchartbase.h

@@ -33,32 +33,88 @@
 /** \brief This is a base-class for all bar graphs with vertical or horizontal orientation (the orientation is implemented in dervied classes!)
  *  \ingroup jkqtplotter_barcharts
  *
- *  This class plots a bargraph. This image explains the parameters:
+ *  This class provides basic properties and functionality for plotting a bargraph.
+ *  The latter is defined by a series of datapoints \c (x,y=f(x)) .
+ *  Bars are then drawn fromm a baseline (often \c =0 ) to the value \c y=f(x) at each position \c x.
+ *  Thus the class is derived from JKQTPXYBaselineGraph, which provides a baseline as well as columns for \c x and \c y values.
+ *
+ *  The width of each bar is determined from its distance to its direct neighbors. It occupies a fraction "width" (JKQTPBarGraphBase::setWidth(), JKQTPBarGraphBase::getWidth() )
+ *  of the available space. Typically \c width=0.9 so the bars occupy most space, but do not touch:
+ *
+ *  \image html bargraph_basics_width.png
+ *
+ *  \see JKQTPBarHorizontalGraph, JKQTPBarVerticalGraph for implementations of this virtual base class.
+ *
+ *
+ *  \section JKQTPBarGraphBase_SideBySide several JKQTPBarGraphBase side-by-side
+ *
+ *  If you draw several JKQTPBarGraphBase of the same orientation (vertical or honrizontal) into the same plot, these will by default
+ *  overlap, if all of the use the same x-values and have the same initial width parameter.
+ *  Typically in such a case, you want to group the bars by x-values and ensure they are drawn side-by-side and do not overlap (or overlap slightly in a controlled way).
+ *
+ *  To achieve this, an addition shift parameter (JKQTPBarGraphBase::setShift(), JKQTPBarGraphBase::getShift() ) was introduced, which moves each bar inside the available space:
  *
  *  \image html bargraph_basics.png
  *
- *  By default the sift parameter is, so the bar is centered at the x-value. The width is 0.9,
+ *  By default the shift parameter (see JKQTPBarGraphBase::setShift() ) is, so the bar is centered at the x-value (i.e. \c shift=0 ).
- *  so adjacent bars are plotted with a small distance between them. It is possible to use these two parameters
+ *
- *  to plot multiple bars for every x-value, by having on JKQTPSpecialLineHorizontalGraph object per
+ *  You can now use shift to separate three JKQTPBarGraphBase in a graph, by setting e.g.:
- *  set of bars that belong together. For example for three bars per x-value one would set:
  *  \verbatim
  *        width=0.3
  *        shift=-0.3 / 0 / +0.3
  *  \endverbatim
+ *
+ *  For convenience, two functions are provided (JKQTPBarGraphBase::autoscaleBarWidthAndShift(), JKQTPBarGraphBase::autoscaleBarWidthAndShiftSeparatedGroups() )
+ *  that can be applied to any JKQTPBarGraphBase in the plot and will calculate all bargraphs' shift and width parameter
+ *  in such a way that the graphs appear tidied up into groups as above. With these functions you don't have to calculate
+ *  the shift and width values by hand! A call always only affects the JKQTPBarGraphBase in the plot with the same orientation
+ *  (vertical or horizontal).
+ *
  *  This results in a bargraph, as shown here:
  *
  *  \image html JKQTPBarVerticalGraph.png
  *
- *  You can also set JKQTPBarGraphBase::FillMode::TwoColorFilling, which uses different fill styles for bars above and below
+ *  \section JKQTPBarGraphBaseStyling Basic Bargraph Styling
- *  the baseline of the graph:
+ *
+ *  There are several options that allow to style the barchraph. The most direct way is to use the setters from
+ *    - JKQTPGraphLineStyleMixin
+ *    - JKQTPGraphFillStyleMixin
+ *  .
+ *  that are available in the class and that allow directly chaning the appearance.
+ *  It is also possibly to draw the baseline itself (\c JKQTPBarGraphBase::setDrawBaseline(true) ).
+ *  Its style is defined in JKQTPBarGraphBase::baselineStyle() .
+ *
+ *  Several convenience functions allow to set these properties in a simplified way:
+ *    - JKQTPBarGraphBase::setFillColor_and_darkenedColor()
+ *  .
+ *
+ *  By default this class will draw boxes for each bar. They can be rounded at the corners by setting:
+ *    - JKQTPBarGraphBase::setRectRadiusAtValue()
+ *    - JKQTPBarGraphBase::setRectRadiusAtBaseline()
+ *    - JKQTPBarGraphBase::setRectRadius()
+ *  .
+ *
+ *
+ *
+ *  \section JKQTPBarGraphBaseDataDependentFilling Data-Dependent Styling of Bargraphs
+ *
+ *  You can also use <code>JKQTPBarGraphBase::setFillMode(JKQTPBarGraphBase::FillMode::TwoColorFilling)</code>,
+ *  which uses different fill styles for bars above and below the baseline of the graph:
  *
  *  \image html JKQTPBarVerticalGraphTwoColorFilling.png
  *
- *  If you use JKQTPBarGraphBase::FillMode::FunctorFilling you can specify the fill style by a functor, e.g.
+ *  The styles for above the baseline is set by the inherited JKQTPGraphLineStyleMixin and JKQTPGraphFillStyleMixin.
+ *  The alternate "below" style, can be modified using
+ *    - JKQTPBarGraphBase::fillStyleBelow()
+ *    - the line-style is the same as from the inherited JKQTPGraphLineStyleMixin
+ *  .
+ *
+ *  If you use <code>JKQTPBarGraphBase::setFillMode(JKQTPBarGraphBase::FillMode::FunctorFilling)</code> you can specify
+ *  the fill style (in the form of a  QBruch) for each bar by a custom functor, e.g.
  *  \code
  *    graph->setFillMode(JKQTPBarGraphBase::FillMode::FunctorFilling);
  *    graph->setFillBrushFunctor(
- *      [](double key, double value) {
+ *      [](double key, double value) -> QBrush {
  *        return QBrush(QColor::fromHsvF(key/12.0, 1.0, 1.0));
  *      }
  *    );
@@ -68,7 +124,11 @@
  *
  *  \image html JKQTPBarVerticalGraphFunctorFilling.png
  *
- *  You can also completely customize the drawing by defining a custom draw functor:
+ *
+ *
+ *  \section JKQTPBarGraphBaseCustomStyling Custom Bargraph Drawing
+ *
+ *  You can also completely customize the drawing by defining a custom draw functor. This allows to draw other shapes than the typical bars:
  *  \code
  *    graph->setCustomDrawingFunctor(
  *      [](JKQTPEnhancedPainter& painter, const QRectF& bar_px, const QPointF& datapoint, Qt::Orientation orientation, JKQTPBarGraphBase* graph) {
@@ -87,9 +147,7 @@
  *  The result may look like this:
  *
  *  \image html JKQTPBarVerticalGraphCustomDrawFunctor.png
-
  *
- *  \see JKQTPBarHorizontalGraph, JKQTPBarVerticalGraph
  */
 class JKQTPLOTTER_LIB_EXPORT JKQTPBarGraphBase: public JKQTPXYBaselineGraph, public JKQTPGraphLineStyleMixin, public JKQTPGraphFillStyleMixin {
         Q_OBJECT