QCPScatterStyle Class Reference

· · ·
Public Types | Public Functions
QCPScatterStyle Class Reference

Represents the visual appearance of scatter points. More...

## Public Types
enum | ScatterShape

## Public Functions
| QCPScatterStyle ()
| QCPScatterStyle (ScatterShape shape, double size=6)
| QCPScatterStyle (ScatterShape shape, const QColor &color, double size)
| QCPScatterStyle (ScatterShape shape, const QColor &color, const QColor &fill, double size)
| QCPScatterStyle (ScatterShape shape, const QPen &pen, const QBrush &brush, double size)
| QCPScatterStyle (const QPixmap &pixmap)
| QCPScatterStyle (const QPainterPath &customPath, const QPen &pen, const QBrush &brush=Qt::NoBrush, double size=6)
double | size () const
ScatterShape | shape () const
QPen | pen () const
QBrush | brush () const
QPixmap | pixmap () const
QPainterPath | customPath () const
void | setSize (double size)
void | setShape (ScatterShape shape)
void | setPen (const QPen &pen)
void | setBrush (const QBrush &brush)
void | setPixmap (const QPixmap &pixmap)
void | setCustomPath (const QPainterPath &customPath)
bool | isNone () const
bool | isPenDefined () const
void | applyTo (QCPPainter *painter, const QPen &defaultPen) const
void | drawShape (QCPPainter *painter, QPointF pos) const
void | drawShape (QCPPainter *painter, double x, double y) const

## Detailed Description

Represents the visual appearance of scatter points.

This class holds information about shape, color and size of scatter points. In plottables like QCPGraph it is used to store how scatter points shall be drawn. For example, QCPGraph::setScatterStyle takes a QCPScatterStyle instance.

A scatter style consists of a shape (setShape), a line color (setPen) and possibly a fill (setBrush), if the shape provides a fillable area. Further, the size of the shape can be controlled with setSize.

# Specifying a scatter style

You can set all these configurations either by calling the respective functions on an instance:

QCPScatterStyle myScatter;
myScatter.setShape(QCPScatterStyle::ssCircle);
myScatter.setPen(Qt::blue);
myScatter.setBrush(Qt::white);
myScatter.setSize(5);
customPlot->graph(0)->setScatterStyle(myScatter);

Or you can use one of the various constructors that take different parameter combinations, making it easy to specify a scatter style in a single call, like so:

customPlot->graph(0)->setScatterStyle(QCPScatterStyle(QCPScatterStyle::ssCircle, Qt::blue, Qt::white, 5));

# Leaving the color/pen up to the plottable

There are two constructors which leave the pen undefined: QCPScatterStyle() and QCPScatterStyle(ScatterShape shape, double size). If those constructors are used, a call to isPenDefined will return false. It leads to scatter points that inherit the pen from the plottable that uses the scatter style. Thus, if such a scatter style is passed to QCPGraph, the line color of the graph (QCPGraph::setPen) will be used by the scatter points. This makes it very convenient to set up typical scatter settings:

customPlot->graph(0)->setScatterStyle(QCPScatterStyle::ssPlus);

Notice that it wasn't even necessary to explicitly call a QCPScatterStyle constructor. This works because QCPScatterStyle provides a constructor that can transform a ScatterShape directly into a QCPScatterStyle instance (that's the QCPScatterStyle(ScatterShape shape, double size) constructor with a default for size). In those cases, C++ allows directly supplying a ScatterShape, where actually a QCPScatterStyle is expected.

# Custom shapes and pixmaps

QCPScatterStyle supports drawing custom shapes and arbitrary pixmaps as scatter points.

For custom shapes, you can provide a QPainterPath with the desired shape to the setCustomPath function or call the constructor that takes a painter path. The scatter shape will automatically be set to ssCustom.

For pixmaps, you call setPixmap with the desired QPixmap. Alternatively you can use the constructor that takes a QPixmap. The scatter shape will automatically be set to ssPixmap. Note that setSize does not influence the appearance of the pixmap.

## Member Enumeration Documentation

enum QCPScatterStyle::ScatterShape

Defines the shape used for scatter points.

On plottables/items that draw scatters, the sizes of these visualizations (with exception of ssDot and ssPixmap) can be controlled with the setSize function. Scatters are drawn with the pen and brush specified with setPen and setBrush.

Enumerator:

  ssNone | no scatter symbols are drawn (e.g. in QCPGraph, data only represented with lines)
  ssDot | a single pixel (use ssDisc or ssCircle if you want a round shape with a certain radius)
  ssCross | a cross
  ssPlus | a plus
  ssCircle | a circle
  ssDisc | a circle which is filled with the pen's color (not the brush as with ssCircle)
  ssSquare | a square
  ssDiamond | a diamond
  ssStar | a star with eight arms, i.e. a combination of cross and plus
  ssTriangle | an equilateral triangle, standing on baseline
  ssTriangleInverted | an equilateral triangle, standing on corner
  ssCrossSquare | a square with a cross inside
  ssPlusSquare | a square with a plus inside
  ssCrossCircle | a circle with a cross inside
  ssPlusCircle | a circle with a plus inside
  ssPeace | a circle, with one vertical and two downward diagonal lines
  ssPixmap | a custom pixmap specified by setPixmap, centered on the data point coordinates
  ssCustom | custom painter operations are performed per scatter (As QPainterPath, see setCustomPath)

## Constructor & Destructor Documentation

QCPScatterStyle::QCPScatterStyle | ( |  | ) |

Creates a new QCPScatterStyle instance with size set to 6. No shape, pen or brush is defined.

Since the pen is undefined (isPenDefined returns false), the scatter color will be inherited from the plottable that uses this scatter style.

QCPScatterStyle::QCPScatterStyle | ( | ScatterShape | shape,
|  | double | size = `6`
| ) |  |

Creates a new QCPScatterStyle instance with shape set to shape and size to size. No pen or brush is defined.

Since the pen is undefined (isPenDefined returns false), the scatter color will be inherited from the plottable that uses this scatter style.

QCPScatterStyle::QCPScatterStyle | ( | ScatterShape | shape,
|  | const QColor & | color,
|  | double | size
| ) |  |

Creates a new QCPScatterStyle instance with shape set to shape, the pen color set to color, and size to size. No brush is defined, i.e. the scatter point will not be filled.

QCPScatterStyle::QCPScatterStyle | ( | ScatterShape | shape,
|  | const QColor & | color,
|  | const QColor & | fill,
|  | double | size
| ) |  |

Creates a new QCPScatterStyle instance with shape set to shape, the pen color set to color, the brush color to fill (with a solid pattern), and size to size.

QCPScatterStyle::QCPScatterStyle | ( | ScatterShape | shape,
|  | const QPen & | pen,
|  | const QBrush & | brush,
|  | double | size
| ) |  |

Creates a new QCPScatterStyle instance with shape set to shape, the pen set to pen, the brush to brush, and size to size.

Warning
  In some cases it might be tempting to directly use a pen style like `Qt::NoPen` as pen and a color like `Qt::blue` as brush. Notice however, that the corresponding call
  `QCPScatterStyle(QCPScatterShape::ssCircle, Qt::NoPen, Qt::blue, 5)`
  doesn't necessarily lead C++ to use this constructor in some cases, but might mistake `Qt::NoPen` for a QColor and use the QCPScatterStyle(ScatterShape shape, const QColor &color, const QColor &fill, double size) constructor instead (which will lead to an unexpected look of the scatter points). To prevent this, be more explicit with the parameter types. For example, use `QBrush(Qt::blue)` instead of just `Qt::blue`, to clearly point out to the compiler that this constructor is wanted.

QCPScatterStyle::QCPScatterStyle | ( | const QPixmap & | pixmap | ) |

Creates a new QCPScatterStyle instance which will show the specified pixmap. The scatter shape is set to ssPixmap.

QCPScatterStyle::QCPScatterStyle | ( | const QPainterPath & | customPath,
|  | const QPen & | pen,
|  | const QBrush & | brush = `Qt::NoBrush`,
|  | double | size = `6`
| ) |  |

Creates a new QCPScatterStyle instance with a custom shape that is defined via customPath. The scatter shape is set to ssCustom.

The custom shape line will be drawn with pen and filled with brush. The size has a slightly different meaning than for built-in scatter points: The custom path will be drawn scaled by a factor of size/6.0. Since the default size is 6, the custom path will appear at a its natural size by default. To double the size of the path for example, set size to 12.

## Member Function Documentation

void QCPScatterStyle::setSize | ( | double | size | ) |

Sets the size (pixel diameter) of the drawn scatter points to size.

See Also
  setShape

void QCPScatterStyle::setShape | ( | QCPScatterStyle::ScatterShape | shape | ) |

Sets the shape to shape.

Note that the calls setPixmap and setCustomPath automatically set the shape to ssPixmap and ssCustom, respectively.

See Also
  setSize

void QCPScatterStyle::setPen | ( | const QPen & | pen | ) |

Sets the pen that will be used to draw scatter points to pen.

If the pen was previously undefined (see isPenDefined), the pen is considered defined after a call to this function, even if pen is `Qt::NoPen`.

See Also
  setBrush

void QCPScatterStyle::setBrush | ( | const QBrush & | brush | ) |

Sets the brush that will be used to fill scatter points to brush. Note that not all scatter shapes have fillable areas. For example, ssPlus does not while ssCircle does.

See Also
  setPen

void QCPScatterStyle::setPixmap | ( | const QPixmap & | pixmap | ) |

Sets the pixmap that will be drawn as scatter point to pixmap.

Note that setSize does not influence the appearance of the pixmap.

The scatter shape is automatically set to ssPixmap.

void QCPScatterStyle::setCustomPath | ( | const QPainterPath & | customPath | ) |

Sets the custom shape that will be drawn as scatter point to customPath.

The scatter shape is automatically set to ssCustom.

bool QCPScatterStyle::isNone | ( |  | ) | const
| inline

Returns whether the scatter shape is ssNone.

See Also
  setShape

bool QCPScatterStyle::isPenDefined | ( |  | ) | const
| inline

Returns whether a pen has been defined for this scatter style.

The pen is undefined if a constructor is called that does not carry pen as parameter. Those are QCPScatterStyle() and QCPScatterStyle(ScatterShape shape, double size). If the pen is left undefined, the scatter color will be inherited from the plottable that uses this scatter style.

See Also
  setPen

void QCPScatterStyle::applyTo | ( | QCPPainter * | painter,
|  | const QPen & | defaultPen
| ) |  | const

Applies the pen and the brush of this scatter style to painter. If this scatter style has an undefined pen (isPenDefined), sets the pen of painter to defaultPen instead.

This function is used by plottables (or any class that wants to draw scatters) just before a number of scatters with this style shall be drawn with the painter.

See Also
  drawShape

void QCPScatterStyle::drawShape | ( | QCPPainter * | painter,
|  | QPointF | pos
| ) |  | const

Draws the scatter shape with painter at position pos.

This function does not modify the pen or the brush on the painter, as applyTo is meant to be called before scatter points are drawn with drawShape.

See Also
  applyTo

void QCPScatterStyle::drawShape | ( | QCPPainter * | painter,
|  | double | x,
|  | double | y
| ) |  | const

This is an overloaded function.

Draws the scatter shape with painter at position x and y.

The documentation for this class was generated from the following files:

- src/painter.h
- src/painter.cpp

Generated with Doxygen 1.8.1.2