KPlotting 5.109.0
Public Types | Properties | Public Slots | Public Member Functions | Protected Member Functions | List of all members
KPlotWidget

Generic data plotting widget. More...

#include <kplotwidget.h>

Public Types

enum  Axis { LeftAxis = 0 , BottomAxis , RightAxis , TopAxis }
 The four types of plot axes. More...
 

Properties

QColor backgroundColor
 
int bottomPadding
 
QColor foregroundColor
 
bool grid
 
QColor gridColor
 
int leftPadding
 
bool objectToolTip
 
int rightPadding
 
int topPadding
 

Public Slots

void setObjectToolTipShown (bool show)
 Toggle the display of a tooltip for point objects.
 
void setShowGrid (bool show)
 Toggle whether grid lines are drawn at major tickmarks.
 

Public Member Functions

 KPlotWidget (QWidget *parent=nullptr)
 Constructor.
 
 ~KPlotWidget () override
 Destructor.
 
void addPlotObject (KPlotObject *object)
 Add an item to the list of KPlotObjects to be plotted.
 
void addPlotObjects (const QList< KPlotObject * > &objects)
 Add more than one KPlotObject at one time.
 
bool antialiasing () const
 
KPlotAxisaxis (Axis type)
 
const KPlotAxisaxis (Axis type) const
 
QColor backgroundColor () const
 
int bottomPadding () const
 
void clearSecondaryLimits ()
 Unset the secondary limits, so the top and right axes show the same tickmarks as the bottom and left axes (no tickmark labels will be drawn for the top and right axes in this case)
 
QRectF dataRect () const
 
QColor foregroundColor () const
 
QColor gridColor () const
 
bool isGridShown () const
 
bool isObjectToolTipShown () const
 
int leftPadding () const
 
QPointF mapToWidget (const QPointF &p) const
 Map a coordinate.
 
void maskAlongLine (const QPointF &p1, const QPointF &p2, float value=1.0f)
 Indicate that object labels should try to avoid the line joining the two given points (in pixel coordinates).
 
void maskRect (const QRectF &r, float value=1.0f)
 Indicate that object labels should try to avoid the given rectangle in the plot.
 
QSize minimumSizeHint () const override
 
QRect pixRect () const
 
void placeLabel (QPainter *painter, KPlotPoint *pp)
 Place an object label optimally in the plot.
 
QList< KPlotObject * > plotObjects () const
 
void removeAllPlotObjects ()
 Removes all plot objects that were added to the widget.
 
void replacePlotObject (int i, KPlotObject *o)
 Replace an item in the KPlotObject list.
 
void resetPlot ()
 Clear the object list, reset the data limits, and remove axis labels If auto-delete was not disabled, the plot objects are deleted.
 
void resetPlotMask ()
 Reset the mask used for non-overlapping labels so that all regions of the plot area are considered empty.
 
int rightPadding () const
 
QRectF secondaryDataRect () const
 
void setAntialiasing (bool b)
 Toggle antialiased drawing.
 
void setAutoDeletePlotObjects (bool autoDelete)
 Enables auto-deletion of plot objects if autoDelete is true; otherwise auto-deletion is disabled.
 
void setBackgroundColor (const QColor &bg)
 Set the background color.
 
void setBottomPadding (int padding)
 Set the number of pixels below the plot area.
 
void setDefaultPaddings ()
 Revert all four padding values to -1, so that they will be automatically determined.
 
void setForegroundColor (const QColor &fg)
 Set the foreground color.
 
void setGridColor (const QColor &gc)
 Set the grid color.
 
void setLeftPadding (int padding)
 Set the number of pixels to the left of the plot area.
 
void setLimits (double x1, double x2, double y1, double y2)
 Set new data limits for the plot.
 
void setRightPadding (int padding)
 Set the number of pixels to the right of the plot area.
 
void setSecondaryLimits (double x1, double x2, double y1, double y2)
 Reset the secondary data limits, which control the values displayed along the top and right axes.
 
void setTopPadding (int padding)
 Set the number of pixels above the plot area.
 
QSize sizeHint () const override
 
int topPadding () const
 

Protected Member Functions

virtual void drawAxes (QPainter *p)
 Draws the plot axes and axis labels.
 
bool event (QEvent *) override
 Generic event handler.
 
void paintEvent (QPaintEvent *) override
 The paint event handler, executed when update() or repaint() is called.
 
QList< KPlotPoint * > pointsUnderPoint (const QPoint &p) const
 
void resizeEvent (QResizeEvent *) override
 The resize event handler, called when the widget is resized.
 
void setPixRect ()
 Synchronize the PixRect with the current widget size and padding settings.
 

Detailed Description

Generic data plotting widget.

Widget for drawing plots. The basic idea behind KPlotWidget is that you don't have to worry about any transformation from your data's natural units to screen pixel coordinates; this is handled internally by the widget.

Data to be plotted are represented by one or more instances of KPlotObject. KPlotObject contains a list of QPointFs to be plotted (again, in the data's natural units), as well as information about how the data are to be rendered in the plot (i.e., as separate points or connected by lines? With what color and point style? etc). See KPlotObject for more information.

KPlotWidget automatically adds axis labels with tickmarks and tick labels. These are encapsulated in the KPlotAxis class. All you have to do is set the limits of the plotting area in data units, and KPlotWidget will figure out the optimal positions and labels for the tickmarks on the axes.

Example of usage:

KPlotWidget *kpw = new KPlotWidget( parent );
// setting our limits for the plot
kpw->setLimits( 1.0, 5.0, 1.0, 25.0 );
// creating a plot object whose points are connected by red lines ...
// ... adding some points to it ...
for ( float x = 1.0; x <= 5.0; x += 0.1 )
kpo->addPoint( x, x*x );
// ... and adding the object to the plot widget
kpw->addPlotObject( kpo );
Encapsulates a data set to be plotted in a KPlotWidget.
Definition kplotobject.h:41
void addPoint(const QPointF &p, const QString &label=QString(), double barWidth=0.0)
Add a point to the object's list of points, using input data to construct a KPlotPoint.
@ Lines
each KPlotPoint is connected with a line
Definition kplotobject.h:55
Generic data plotting widget.
Definition kplotwidget.h:68
void setLimits(double x1, double x2, double y1, double y2)
Set new data limits for the plot.
void addPlotObject(KPlotObject *object)
Add an item to the list of KPlotObjects to be plotted.
Note
KPlotWidget will take ownership of the objects added to it, so when clearing the objects list (eg with removeAllPlotObjects()) any previous reference to a KPlotObject already added to a KPlotWidget will be invalid. You can disable this behavior by using setAutoDelete(false).
Author
Jason Harris

Member Enumeration Documentation

◆ Axis

The four types of plot axes.

Enumerator
LeftAxis 

the left axis

BottomAxis 

the bottom axis

RightAxis 

the right axis

TopAxis 

the top axis

Constructor & Destructor Documentation

◆ KPlotWidget()

KPlotWidget::KPlotWidget ( QWidget *  parent = nullptr)
explicit

Constructor.

Parameters
parentthe parent widget

◆ ~KPlotWidget()

KPlotWidget::~KPlotWidget ( )
override

Destructor.

Member Function Documentation

◆ addPlotObject()

void KPlotWidget::addPlotObject ( KPlotObject object)

Add an item to the list of KPlotObjects to be plotted.

The widget takes ownership of the plot object, unless auto-delete was disabled.

Parameters
objectthe KPlotObject to be added

◆ addPlotObjects()

void KPlotWidget::addPlotObjects ( const QList< KPlotObject * > &  objects)

Add more than one KPlotObject at one time.

The widget takes ownership of the plot object, unless auto-delete was disabled.

Parameters
objectsthe list of KPlotObjects to be added

◆ antialiasing()

bool KPlotWidget::antialiasing ( ) const
Returns
whether the antialiasing is active Antialiasing is not active by default.

◆ axis() [1/2]

KPlotAxis * KPlotWidget::axis ( Axis  type)
Returns
the axis of the specified type, or 0 if no axis has been set.
See also
Axis

◆ axis() [2/2]

const KPlotAxis * KPlotWidget::axis ( Axis  type) const
Returns
the axis of the specified type, or 0 if no axis has been set.
See also
Axis

◆ backgroundColor()

QColor KPlotWidget::backgroundColor ( ) const
Returns
the background color of the plot.

The default color is black.

◆ bottomPadding()

int KPlotWidget::bottomPadding ( ) const
Returns
the number of pixels below the plot area. Padding values are set to -1 by default; if unchanged, this function will try to guess a good value, based on whether ticklabels and/or axis labels are to be drawn.

◆ clearSecondaryLimits()

void KPlotWidget::clearSecondaryLimits ( )

Unset the secondary limits, so the top and right axes show the same tickmarks as the bottom and left axes (no tickmark labels will be drawn for the top and right axes in this case)

◆ dataRect()

QRectF KPlotWidget::dataRect ( ) const
Returns
the rectangle representing the boundaries of the current plot, in natural data units.
See also
setLimits()

◆ drawAxes()

virtual void KPlotWidget::drawAxes ( QPainter *  p)
protectedvirtual

Draws the plot axes and axis labels.

◆ event()

bool KPlotWidget::event ( QEvent *  )
overrideprotected

Generic event handler.

◆ foregroundColor()

QColor KPlotWidget::foregroundColor ( ) const
Returns
the foreground color, used for axes, tickmarks and associated labels.

The default color is white.

◆ gridColor()

QColor KPlotWidget::gridColor ( ) const
Returns
the grid color.

The default color is gray.

◆ isGridShown()

bool KPlotWidget::isGridShown ( ) const
Returns
whether the grid lines are shown Grid lines are not shown by default.

◆ isObjectToolTipShown()

bool KPlotWidget::isObjectToolTipShown ( ) const
Returns
whether the tooltip for the point objects is shown. Tooltips are enabled by default.

◆ leftPadding()

int KPlotWidget::leftPadding ( ) const
Returns
the number of pixels to the left of the plot area.

Padding values are set to -1 by default; if unchanged, this function will try to guess a good value, based on whether ticklabels and/or axis labels need to be drawn.

◆ mapToWidget()

QPointF KPlotWidget::mapToWidget ( const QPointF &  p) const

Map a coordinate.

Parameters
pfrom the data rect to the physical pixel rect. Used mainly when drawing.
pthe point to be converted, in natural data units
Returns
the coordinate in the pixel coordinate system

◆ maskAlongLine()

void KPlotWidget::maskAlongLine ( const QPointF &  p1,
const QPointF &  p2,
float  value = 1.0f 
)

Indicate that object labels should try to avoid the line joining the two given points (in pixel coordinates).

Note
You should not normally call this function directly. It is called by KPlotObject when lines are drawn in the plot.
Parameters
p1the starting point for the line
p2the ending point for the line
valueAllows you to determine how strongly the line should be avoided. Larger values are avoided more strongly.

◆ maskRect()

void KPlotWidget::maskRect ( const QRectF &  r,
float  value = 1.0f 
)

Indicate that object labels should try to avoid the given rectangle in the plot.

The rectangle is in pixel coordinates.

Note
You should not normally call this function directly. It is called by KPlotObject when points, bars and labels are drawn.
Parameters
rthe rectangle defining the region in the plot that text labels should avoid (in pixel coordinates)
valueAllows you to determine how strongly the rectangle should be avoided. Larger values are avoided more strongly.

◆ minimumSizeHint()

QSize KPlotWidget::minimumSizeHint ( ) const
override
Returns
suggested minimum size for the plot widget

◆ paintEvent()

void KPlotWidget::paintEvent ( QPaintEvent *  )
overrideprotected

The paint event handler, executed when update() or repaint() is called.

◆ pixRect()

QRect KPlotWidget::pixRect ( ) const
Returns
the rectangle representing the boundaries of the current plot, in screen pixel units.

◆ placeLabel()

void KPlotWidget::placeLabel ( QPainter *  painter,
KPlotPoint pp 
)

Place an object label optimally in the plot.

This function will attempt to place the label as close as it can to the point to which the label belongs, while avoiding overlap with regions of the plot that have been masked.

Note
You should not normally call this function directly. It is called internally in KPlotObject::draw().
Parameters
painterPointer to the painter on which to draw the label
pppointer to the KPlotPoint whose label is to be drawn.

◆ plotObjects()

QList< KPlotObject * > KPlotWidget::plotObjects ( ) const
Returns
the current list of plot objects

◆ pointsUnderPoint()

QList< KPlotPoint * > KPlotWidget::pointsUnderPoint ( const QPoint &  p) const
protected
Returns
a list of points in the plot which are within 4 pixels of the screen position given as an argument.
Parameters
pThe screen position from which to check for plot points.

◆ removeAllPlotObjects()

void KPlotWidget::removeAllPlotObjects ( )

Removes all plot objects that were added to the widget.

If auto-delete was not disabled, the plot objects are deleted.

◆ replacePlotObject()

void KPlotWidget::replacePlotObject ( int  i,
KPlotObject o 
)

Replace an item in the KPlotObject list.

Parameters
ithe index of the item to be replaced
opointer to the replacement KPlotObject
Since
5.12, if auto-deletion is enabled, the previous plot object is deleted. Call setAutoDeletePlotObjects(false) if you want to swap between available plot objects and therefore you want to handle deletion externally.

◆ resetPlot()

void KPlotWidget::resetPlot ( )

Clear the object list, reset the data limits, and remove axis labels If auto-delete was not disabled, the plot objects are deleted.

◆ resetPlotMask()

void KPlotWidget::resetPlotMask ( )

Reset the mask used for non-overlapping labels so that all regions of the plot area are considered empty.

◆ resizeEvent()

void KPlotWidget::resizeEvent ( QResizeEvent *  )
overrideprotected

The resize event handler, called when the widget is resized.

◆ rightPadding()

int KPlotWidget::rightPadding ( ) const
Returns
the number of pixels to the right of the plot area. Padding values are set to -1 by default; if unchanged, this function will try to guess a good value, based on whether ticklabels and/or axis labels are to be drawn.

◆ secondaryDataRect()

QRectF KPlotWidget::secondaryDataRect ( ) const
Returns
the rectangle representing the boundaries of the secondary data limits, if they have been set. Otherwise, this function behaves the same as dataRect().
See also
setSecondaryLimits()

◆ setAntialiasing()

void KPlotWidget::setAntialiasing ( bool  b)

Toggle antialiased drawing.

Parameters
bif true, the plot graphics will be antialiased.

◆ setAutoDeletePlotObjects()

void KPlotWidget::setAutoDeletePlotObjects ( bool  autoDelete)

Enables auto-deletion of plot objects if autoDelete is true; otherwise auto-deletion is disabled.

Auto-deletion is enabled by default.

Since
5.12

◆ setBackgroundColor()

void KPlotWidget::setBackgroundColor ( const QColor &  bg)

Set the background color.

Parameters
bgthe new background color

◆ setBottomPadding()

void KPlotWidget::setBottomPadding ( int  padding)

Set the number of pixels below the plot area.

Set this to -1 to revert to automatic determination of padding values.

◆ setDefaultPaddings()

void KPlotWidget::setDefaultPaddings ( )

Revert all four padding values to -1, so that they will be automatically determined.

◆ setForegroundColor()

void KPlotWidget::setForegroundColor ( const QColor &  fg)

Set the foreground color.

Parameters
fgthe new foreground color

◆ setGridColor()

void KPlotWidget::setGridColor ( const QColor &  gc)

Set the grid color.

Parameters
gcthe new grid color

◆ setLeftPadding()

void KPlotWidget::setLeftPadding ( int  padding)

Set the number of pixels to the left of the plot area.

Set this to -1 to revert to automatic determination of padding values.

◆ setLimits()

void KPlotWidget::setLimits ( double  x1,
double  x2,
double  y1,
double  y2 
)

Set new data limits for the plot.

Parameters
x1the minimum X value in data units
x2the maximum X value in data units
y1the minimum Y value in data units
y2the maximum Y value in data units

◆ setObjectToolTipShown

void KPlotWidget::setObjectToolTipShown ( bool  show)
slot

Toggle the display of a tooltip for point objects.

Parameters
showwhether show the tooltip.
See also
isObjectToolTipShown()

◆ setPixRect()

void KPlotWidget::setPixRect ( )
protected

Synchronize the PixRect with the current widget size and padding settings.

◆ setRightPadding()

void KPlotWidget::setRightPadding ( int  padding)

Set the number of pixels to the right of the plot area.

Set this to -1 to revert to automatic determination of padding values.

◆ setSecondaryLimits()

void KPlotWidget::setSecondaryLimits ( double  x1,
double  x2,
double  y1,
double  y2 
)

Reset the secondary data limits, which control the values displayed along the top and right axes.

All data points are plotted using the coordinates defined by setLimits(), so this function is only useful for showing alternate tickmark labels along the top and right edges. For example, if you were plotting temperature on the X-axis, you could use Centigrade units for the primary (bottom) axis, using setLimits( 0.0, 100.0, 0.0, 1.0 ). If you also wanted to show Fahrenheit units along the secondary (top) axis, you would additionally use setSecondaryLimits( 32.0, 212.0, 0.0, 1.0 ). The data added to the plot would have x-coordinates in Centigrade degrees.

Parameters
x1the minimum X value in secondary data units
x2the maximum X value in secondary data units
y1the minimum Y value in secondary data units
y2the maximum Y value in secondary data units
See also
setLimits()

◆ setShowGrid

void KPlotWidget::setShowGrid ( bool  show)
slot

Toggle whether grid lines are drawn at major tickmarks.

Parameters
showif true, grid lines will be drawn.
See also
isGridShown()

◆ setTopPadding()

void KPlotWidget::setTopPadding ( int  padding)

Set the number of pixels above the plot area.

Set this to -1 to revert to automatic determination of padding values.

◆ sizeHint()

QSize KPlotWidget::sizeHint ( ) const
override
Returns
suggested size for the plot widget

◆ topPadding()

int KPlotWidget::topPadding ( ) const
Returns
the number of pixels above the plot area. Padding values are set to -1 by default; if unchanged, this function will try to guess a good value, based on whether ticklabels and/or axis labels are to be drawn.