/*! \defgroup jkqtplotter_general_usage Usage of JKQTPlotter \ingroup jkqtplotter_general \see See \ref page_buildinstructions for detailed build-instructions and on how to link against JKQTPlotter! \defgroup jkqtplotter_general_usage_jkqtbaseplotter Usage of JKQTBasePlotter Non-Visible Class \ingroup jkqtplotter_general_usage It is also possible to use it in a standalone fashion to generate plots without generating a window. Note that the baseplotter class still requires the \c widgets+gui modules of Qt, because it contains code to e.g. display pint or export preview dialogs! Here is an example of how to do this (it is taken from the command-line tool \ref JKQTPlotterDocImageRenderCmdLineTool): First we generate the JKQTBasePlotter object and add some data to the internal JKQTPDatastore \code JKQTBasePlotter plot(true); JKQTPDatastore* ds=plot.getDatastore(); size_t cx=ds->addCopiedColumn(QVector{-1.5,-0.5,0.5,1.5,2.5},"x"); size_t cy=ds->addCopiedColumn(QVector{-0.75,-0.3,-0.05,0.2,0.65},"y"); \endcode Now we set the range of x/y plot coordinates ... \code plot.setXY(-0.8,2.2,-0.5,0.7); \endcode and the size of the widget, i.e. the size of the plot in the windowing system. \code plot.setWidgetSize(150,50); \endcode Now we can add graphs to the plotter, e.g. \code JKQTPXYLineGraph* g=new JKQTPXYLineGraph(&plot); g->setXColumn(cx); g->setYColumn(cy); plot.addGraph(g); \endcode Finally we store an image of the plot as PNG-file: \code plot.saveAsPixelImage("output.png", false, "png"); \endcode Alternatively you can obtain a QImage of the plot using JKQTBasePlotter::grabPixelImage() or copy the image to the clipboard using JKQTBasePlotter::copyPixelImage(). Also storages as PDF and SVG is available via JKQTBasePlotter::saveAsPDF() and JKQTBasePlotter::saveAsSVG(). With simlar code you can also integrate JKQTBasePlotter into your own widgets. This class is immpleented in a such a way that different instances can be used in different parallel threads, i.e. the class is re-entrant. There are however access to different cached data is synchronized between all threads (i.e. static internal caches are used), which limmits the acheavable parallelization speedup! See \ref JKQTPlotterMultiThreaded for an example of multi-threaded plotting! \defgroup jkqtplotter_general_usage_jkqtplotter Usage of JKQTPlotter Widget \ingroup jkqtplotter_general_usage JKQTPlotter is a plotter widget which wraps around a JKQTBasePlotter instanced that does the actual drawing. A basic usage of JKQTPlotter looks like this: \code{.cpp} // create a new JKQTPlotter instance JKQTPlotter* plot = new JKQTPlotter(parentWidget); // fill two vectors with dtaa for a graph: QVector X, Y; fillDataVectors(X, Y); // make data available to the internal datastore of the plotter: size_t columnX=plot->getDatastore()->addCopiedColumn(X, "x"); size_t columnY=plot->getDatastore()->addCopiedColumn(Y, "y"); // create a graph/curve, which displays the data JKQTPXYLineGraph* graph1=new JKQTPXYLineGraph(plot); graph1->setXColumn(columnX); graph1->setYColumn(columnY); graph1->setTitle(QObject::tr("graph title")); plot->addGraph(graph1); // autoscale the plot plot->zoomToFit(); // alternatively set the axis dimension by hand: plot->setXY(-10,10,-10,10); \endcode The result should look something like this: \image html simpletest.png Starting from this basic example, you can observe several important principles:
  1. Data is stored in an (internal) instance of JKQTPDatastore, which is accessible through JKQTPlotter::getDatastore(). This datastore can either own its data (which is done here, as we copy the data into the store by calling JKQTPDatastore::addCopiedColumn(), or it can merely reference to the data (then data needs to be available as array of \c double values).
  2. Naming conventions (excerpt from \ref jkqtplotter_naming ):
    • \b plot is the complete drawn image, including the axes, the graphs, the key and all other visual elements
    • plot element any sub element of the plot, e.g. a single coordinate axis, the key, but also any graph/curve
    • \b graph is a single curve/image/geometric element in the plot
    • geometric element is a special graph that does not represent a curve based on data from the JKQTPDatastore, but a single graphic element, like a rectangle/circle/line/..., some text, a single symbol
    • \b key is the legend of the plot
    • coordinate axis is each of the x- or y-axis (there might be addition axes, e.g. when showing a color-scale)
  3. Each graph is represented by a class derived from JKQTPPlotElement (in the example we instanciated a JKQTPXYLineGraph, which shows data as a scatter of symbols that may (or may not) be connected by a line). Creating the graph class does not yet add it to the plotter. To add it, call JKQTPlotter::addGraph(). Only after this sep, the graph is displayed. You can modify the apperance of the graph (e.g. colors, name in the key ...) by setting properties in the graph class instance.
  4. You can auto-zoom the axis ranges of the plot by calling JKQTPlotter::zoomToFit(), or set them exlicitly by calling JKQTPlotter::setXY(). The user can later zoom in/out by the mouse (and other means). You can limit this zoom range by setting an absolute axis range, calling e.g. JKQTPlotter::setAbsoluteXY(). The the user cannot zoom farther out than the given range(s).
  5. If you want to style the plot itself, you need to set properties of the underlying JKQTBasePloter instance, which is accessible through JKQTPlotter::getPlotter(). If you want to style the coordinate axes, you can acces their representing objects by caling JKQTPlotter::getXAxis() or JKQTPlotter::getYAxis().
\see \ref JKQTPlotterSimpleTest and \see JKQTPlotterQtCreator \defgroup jkqtplotter_general_usage_qtcreator How to use JKQTPlotter in the Qt Form Designer \ingroup jkqtplotter_general_usage As JKQTPlotter is a standard Qt widget, you can also use it in Qt UI-files designed with the Qt From Designer (e.g. from within QTCreator). For this to work you have to use the Promote QWidget"-feature of the form designer. The steps you need to take are detailed below:
  1. add a new UI-file to your project and open it in the Form Editor. Then right-click the form and select `Promote Widgets ...`: \image html uidesigner_step1.png
  2. In the dialog that opens, you have to define `JKQTPlotter` as a promotion to `QWidget` as shown below. Finally store the settings by clicking `Add` and closing the dialog with `Close`. \image html uidesigner_step2.png
  3. Now you can add a `QWidget`from the side-bar to the form and then promote it to `JKQTPlotter`, by selecting and right-clicking the `QWidget` and then selecting `Promote To | JKQTPlotter`: \image html uidesigner_step3.png
\see \ref JKQTPlotterQtCreator
Also see \ref JKQTPlotterStyling for another example of using the Qt UI Designer with JKQTPlotter */