mirror of
https://github.com/jkriege2/JKQtPlotter.git
synced 2024-11-15 18:15:52 +08:00
161 lines
7.5 KiB
Plaintext
161 lines
7.5 KiB
Plaintext
/*!
|
|
|
|
|
|
\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<double>{-1.5,-0.5,0.5,1.5,2.5},"x");
|
|
size_t cy=ds->addCopiedColumn(QVector<double>{-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<double> 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:
|
|
<ol>
|
|
<li> 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).
|
|
<li> Naming conventions (excerpt from \ref jkqtplotter_naming ):
|
|
<ul>
|
|
<li> \b plot is the complete drawn image, including the axes, the graphs, the key and all other visual elements
|
|
<li> <b>plot element</b> any sub element of the plot, e.g. a single coordinate axis, the key, but also any graph/curve
|
|
<li> \b graph is a single curve/image/geometric element in the plot
|
|
<li> <b>geometric element</b> 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
|
|
<li> \b key is the legend of the plot
|
|
<li> <b>coordinate axis</b> is each of the x- or y-axis (there might be addition axes, e.g. when showing a color-scale)
|
|
</ul>
|
|
<li> 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.
|
|
<li> 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).
|
|
<li> 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().
|
|
</ol>
|
|
|
|
\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 <a href="https://doc.qt.io/qt-6/designer-using-custom-widgets.html">Promote QWidget"-feature</a> of the form designer. The steps you need to take are detailed below:
|
|
<ol>
|
|
<li> 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
|
|
</li>
|
|
<li> 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
|
|
</li>
|
|
<li> 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
|
|
</li>
|
|
</ol>
|
|
|
|
\see \ref JKQTPlotterQtCreator <br> Also see \ref JKQTPlotterStyling for another example of using the Qt UI Designer with JKQTPlotter
|
|
|
|
*/
|
|
|
|
|
|
|