Manages a legend inside a QCustomPlot. More...
Public Types | |
enum | PositionStyle |
enum | SelectablePart |
Public Functions | |
QCPLegend (QCustomPlot *parentPlot) | |
QPen | borderPen () const |
QBrush | brush () const |
QFont | font () const |
QColor | textColor () const |
PositionStyle | positionStyle () const |
QPoint | position () const |
bool | autoSize () const |
QSize | size () const |
QSize | minimumSize () const |
int | paddingLeft () const |
int | paddingRight () const |
int | paddingTop () const |
int | paddingBottom () const |
int | marginLeft () const |
int | marginRight () const |
int | marginTop () const |
int | marginBottom () const |
int | itemSpacing () const |
QSize | iconSize () const |
int | iconTextPadding () const |
QPen | iconBorderPen () const |
SelectableParts | selectable () const |
SelectableParts | selected () const |
QPen | selectedBorderPen () const |
QPen | selectedIconBorderPen () const |
QBrush | selectedBrush () const |
QFont | selectedFont () const |
QColor | selectedTextColor () const |
void | setBorderPen (const QPen &pen) |
void | setBrush (const QBrush &brush) |
void | setFont (const QFont &font) |
void | setTextColor (const QColor &color) |
void | setPositionStyle (PositionStyle legendPositionStyle) |
void | setPosition (const QPoint &pixelPosition) |
void | setAutoSize (bool on) |
void | setSize (const QSize &size) |
void | setSize (int width, int height) |
void | setMinimumSize (const QSize &size) |
void | setMinimumSize (int width, int height) |
void | setPaddingLeft (int padding) |
void | setPaddingRight (int padding) |
void | setPaddingTop (int padding) |
void | setPaddingBottom (int padding) |
void | setPadding (int left, int right, int top, int bottom) |
void | setMarginLeft (int margin) |
void | setMarginRight (int margin) |
void | setMarginTop (int margin) |
void | setMarginBottom (int margin) |
void | setMargin (int left, int right, int top, int bottom) |
void | setItemSpacing (int spacing) |
void | setIconSize (const QSize &size) |
void | setIconSize (int width, int height) |
void | setIconTextPadding (int padding) |
void | setIconBorderPen (const QPen &pen) |
void | setSelectable (const SelectableParts &selectable) |
void | setSelected (const SelectableParts &selected) |
void | setSelectedBorderPen (const QPen &pen) |
void | setSelectedIconBorderPen (const QPen &pen) |
void | setSelectedBrush (const QBrush &brush) |
void | setSelectedFont (const QFont &font) |
void | setSelectedTextColor (const QColor &color) |
QCPAbstractLegendItem * | item (int index) const |
QCPPlottableLegendItem * | itemWithPlottable (const QCPAbstractPlottable *plottable) const |
int | itemCount () const |
bool | hasItem (QCPAbstractLegendItem *item) const |
bool | hasItemWithPlottable (const QCPAbstractPlottable *plottable) const |
bool | addItem (QCPAbstractLegendItem *item) |
bool | removeItem (int index) |
bool | removeItem (QCPAbstractLegendItem *item) |
void | clearItems () |
QList< QCPAbstractLegendItem * > | selectedItems () const |
void | reArrange () |
bool | selectTestLegend (const QPointF &pos) const |
QCPAbstractLegendItem * | selectTestItem (const QPoint pos) const |
bool | visible () const |
QCustomPlot * | parentPlot () const |
QCPLayer * | layer () const |
bool | antialiased () const |
void | setVisible (bool on) |
bool | setLayer (QCPLayer *layer) |
bool | setLayer (const QString &layerName) |
void | setAntialiased (bool enabled) |
Signals | |
void | selectionChanged (QCPLegend::SelectableParts selection) |
Protected Functions | |
virtual void | updateSelectionState () |
virtual bool | handleLegendSelection (QMouseEvent *event, bool additiveSelection, bool &modified) |
virtual void | applyDefaultAntialiasingHint (QCPPainter *painter) const |
virtual void | draw (QCPPainter *painter) |
virtual void | calculateAutoSize () |
virtual void | calculateAutoPosition () |
QPen | getBorderPen () const |
QBrush | getBrush () const |
bool | moveToLayer (QCPLayer *layer, bool prepend) |
void | applyAntialiasingHint (QCPPainter *painter, bool localAntialiased, QCP::AntialiasedElement overrideElement) const |
virtual QRect | clipRect () const |
Manages a legend inside a QCustomPlot.
Doesn't need to be instantiated externally, rather access QCustomPlot::legend
Defines where the legend is positioned inside the QCustomPlot axis rect.
psManual |
Position is not changed automatically. Set manually via setPosition. |
psTopLeft |
Legend is positioned in the top left corner of the axis rect with distance to the border corresponding to the currently set top and left margins. |
psTop |
Legend is horizontally centered at the top of the axis rect with distance to the border corresponding to the currently set top margin. |
psTopRight |
Legend is positioned in the top right corner of the axis rect with distance to the border corresponding to the currently set top and right margins. |
psRight |
Legend is vertically centered at the right of the axis rect with distance to the border corresponding to the currently set right margin. |
psBottomRight |
Legend is positioned in the bottom right corner of the axis rect with distance to the border corresponding to the currently set bottom and right margins. |
psBottom |
Legend is horizontally centered at the bottom of the axis rect with distance to the border corresponding to the currently set bottom margin. |
psBottomLeft |
Legend is positioned in the bottom left corner of the axis rect with distance to the border corresponding to the currently set bottom and left margins. |
psLeft |
Legend is vertically centered at the left of the axis rect with distance to the border corresponding to the currently set left margin. |
Defines the selectable parts of a legend
spNone |
None. |
spLegendBox |
The legend box (frame) |
spItems |
Legend items individually (see selectedItems) |
QCPLegend::QCPLegend | ( | QCustomPlot * | parentPlot | ) | [explicit] |
Constructs a new QCPLegend instance with parentPlot as the containing plot and default values. Under normal usage, QCPLegend needn't be instantiated outside of QCustomPlot. Access QCustomPlot::legend to modify the legend (set to invisible by default, see setVisible).
void QCPLegend::setBorderPen | ( | const QPen & | pen | ) |
Sets the pen, the border of the entire legend is drawn with.
void QCPLegend::setBrush | ( | const QBrush & | brush | ) |
Sets the brush of the legend background.
void QCPLegend::setFont | ( | const QFont & | font | ) |
Sets the default font of legend text. Legend items that draw text (e.g. the name of a graph) will use this font by default. However, a different font can be specified on a per-item-basis by accessing the specific legend item.
This function will also set font on all already existing legend items.
void QCPLegend::setTextColor | ( | const QColor & | color | ) |
Sets the default color of legend text. Legend items that draw text (e.g. the name of a graph) will use this color by default. However, a different colors can be specified on a per-item-basis by accessing the specific legend item.
This function will also set color on all already existing legend items.
void QCPLegend::setPositionStyle | ( | PositionStyle | legendPositionStyle | ) |
Sets the position style of the legend. If the legendPositionStyle is not psManual, the position is found automatically depending on the specific legendPositionStyle and the legend margins. If legendPositionStyle is psManual, the exact pixel position of the legend must be specified via setPosition. Margins have no effect in that case.
void QCPLegend::setPosition | ( | const QPoint & | pixelPosition | ) |
Sets the exact pixel Position of the legend inside the QCustomPlot widget, if setPositionStyle is set to psManual. Margins have no effect in that case.
void QCPLegend::setAutoSize | ( | bool | on | ) |
Sets whether the size of the legend should be calculated automatically to fit all the content (plus padding), or whether the size must be specified manually with setSize.
If the autoSize mechanism is enabled, the legend will have the smallest possible size to still display all its content. For items with text wrapping (QCPPlottableLegendItem::setTextWrap) this means, they would become very compressed, i.e. wrapped at every word. To prevent this, set a reasonable setMinimumSize width.
void QCPLegend::setSize | ( | const QSize & | size | ) |
Sets the size of the legend. Setting the size manually with this function only has an effect, if setAutoSize is set to false.
If you want to control the minimum size (or the text-wrapping width) while still leaving the autoSize mechanism enabled, consider using setMinimumSize.
void QCPLegend::setSize | ( | int | width, |
int | height | ||
) |
This is an overloaded function.
void QCPLegend::setMinimumSize | ( | const QSize & | size | ) |
Sets the minimum size of the legend when setAutoSize is enabled.
If text wrapping is enabled in the legend items (e.g. QCPPlottableLegendItem::setTextWrap), this minimum size defines the width at which the wrapping will occur. Note that the wrapping will happen only at word boundaries, so the actual size might still be bigger than the size given here, but not smaller.
If setAutoSize is not enabled, the minimum size is ignored. Setting a smaller legend size with setSize manually, is not prevented.
void QCPLegend::setMinimumSize | ( | int | width, |
int | height | ||
) |
This is an overloaded function.
void QCPLegend::setPaddingLeft | ( | int | padding | ) |
Sets the left padding of the legend. Padding is the space by what the legend box is made larger than minimally needed for the content to fit. I.e. it's the space left blank on each side inside the legend.
void QCPLegend::setPaddingRight | ( | int | padding | ) |
Sets the right padding of the legend. Padding is the space by what the legend box is made larger than minimally needed for the content to fit. I.e. it's the space left blank on each side inside the legend.
void QCPLegend::setPaddingTop | ( | int | padding | ) |
Sets the top padding of the legend. Padding is the space by what the legend box is made larger than minimally needed for the content to fit. I.e. it's the space left blank on each side inside the legend.
void QCPLegend::setPaddingBottom | ( | int | padding | ) |
Sets the bottom padding of the legend. Padding is the space by what the legend box is made larger than minimally needed for the content to fit. I.e. it's the space left blank on each side inside the legend.
void QCPLegend::setPadding | ( | int | left, |
int | right, | ||
int | top, | ||
int | bottom | ||
) |
Sets the padding of the legend. Padding is the space by what the legend box is made larger than minimally needed for the content to fit. I.e. it's the space left blank on each side inside the legend.
void QCPLegend::setMarginLeft | ( | int | margin | ) |
Sets the left margin of the legend. Margins are the distances the legend will keep to the axis rect, when setPositionStyle is not psManual.
void QCPLegend::setMarginRight | ( | int | margin | ) |
Sets the right margin of the legend. Margins are the distances the legend will keep to the axis rect, when setPositionStyle is not psManual.
void QCPLegend::setMarginTop | ( | int | margin | ) |
Sets the top margin of the legend. Margins are the distances the legend will keep to the axis rect, when setPositionStyle is not psManual.
void QCPLegend::setMarginBottom | ( | int | margin | ) |
Sets the bottom margin of the legend. Margins are the distances the legend will keep to the axis rect, when setPositionStyle is not psManual.
void QCPLegend::setMargin | ( | int | left, |
int | right, | ||
int | top, | ||
int | bottom | ||
) |
Sets the margin of the legend. Margins are the distances the legend will keep to the axis rect, when setPositionStyle is not psManual.
void QCPLegend::setItemSpacing | ( | int | spacing | ) |
Sets the vertical space between two legend items in the legend.
void QCPLegend::setIconSize | ( | const QSize & | size | ) |
Sets the size of legend icons. Legend items that draw an icon (e.g. a visual representation of the graph) will use this size by default.
void QCPLegend::setIconSize | ( | int | width, |
int | height | ||
) |
This is an overloaded function.
void QCPLegend::setIconTextPadding | ( | int | padding | ) |
Sets the horizontal space in pixels between the legend icon and the text next to it. Legend items that draw an icon (e.g. a visual representation of the graph) and text (e.g. the name of the graph) will use this space by default.
void QCPLegend::setIconBorderPen | ( | const QPen & | pen | ) |
Sets the pen used to draw a border around each legend icon. Legend items that draw an icon (e.g. a visual representation of the graph) will use this pen by default.
If no border is wanted, set this to Qt::NoPen.
void QCPLegend::setSelectable | ( | const SelectableParts & | selectable | ) |
Sets whether the user can (de-)select the parts in selectable by clicking on the QCustomPlot surface. (When QCustomPlot::setInteractions contains iSelectLegend.)
However, even when selectable is set to a value not allowing the selection of a specific part, it is still possible to set the selection of this part manually, by calling setSelected directly.
void QCPLegend::setSelected | ( | const SelectableParts & | selected | ) |
Sets the selected state of the respective legend parts described by SelectablePart. When a part is selected, it uses a different pen/font and brush. If some legend items are selected and selected doesn't contain spItems, those items become deselected.
The entire selection mechanism is handled automatically when QCustomPlot::setInteractions contains iSelectLegend. You only need to call this function when you wish to change the selection state manually.
This function can change the selection state of a part even when setSelectable was set to a value that actually excludes the part.
emits the selectionChanged signal when selected is different from the previous selection state.
Note that it doesn't make sense to set the selected state spItems here when it wasn't set before, because there's no way to specify which exact items to newly select. Do this by calling QCPAbstractLegendItem::setSelected directly on the legend item you wish to select.
void QCPLegend::setSelectedBorderPen | ( | const QPen & | pen | ) |
When the legend box is selected, this pen is used to draw the border instead of the normal pen set via setBorderPen.
void QCPLegend::setSelectedIconBorderPen | ( | const QPen & | pen | ) |
Sets the pen legend items will use to draw their icon borders, when they are selected.
void QCPLegend::setSelectedBrush | ( | const QBrush & | brush | ) |
When the legend box is selected, this brush is used to draw the legend background instead of the normal brush set via setBrush.
void QCPLegend::setSelectedFont | ( | const QFont & | font | ) |
Sets the default font that is used by legend items when they are selected.
This function will also set font on all already existing legend items.
void QCPLegend::setSelectedTextColor | ( | const QColor & | color | ) |
Sets the default text color that is used by legend items when they are selected.
This function will also set color on all already existing legend items.
QCPAbstractLegendItem * QCPLegend::item | ( | int | index | ) | const |
Returns the item with index i.
QCPPlottableLegendItem * QCPLegend::itemWithPlottable | ( | const QCPAbstractPlottable * | plottable | ) | const |
Returns the QCPPlottableLegendItem which is associated with plottable (e.g. a QCPGraph*). If such an item isn't in the legend, returns 0.
int QCPLegend::itemCount | ( | ) | const |
Returns the number of items currently in the legend.
bool QCPLegend::hasItem | ( | QCPAbstractLegendItem * | item | ) | const |
Returns whether the legend contains item.
bool QCPLegend::hasItemWithPlottable | ( | const QCPAbstractPlottable * | plottable | ) | const |
Returns whether the legend contains a QCPPlottableLegendItem which is associated with plottable (e.g. a QCPGraph*). If such an item isn't in the legend, returns false.
bool QCPLegend::addItem | ( | QCPAbstractLegendItem * | item | ) |
Adds item to the legend, if it's not present already.
Returns true on sucess, i.e. if the item wasn't in the list already and has been successfuly added.
The legend takes ownership of the item.
bool QCPLegend::removeItem | ( | int | index | ) |
Removes the item with index index from the legend.
Returns true, if successful.
bool QCPLegend::removeItem | ( | QCPAbstractLegendItem * | item | ) |
This is an overloaded function.
Removes item from the legend.
Returns true, if successful.
void QCPLegend::clearItems | ( | ) |
Removes all items from the legend.
QList< QCPAbstractLegendItem * > QCPLegend::selectedItems | ( | ) | const |
Returns the legend items that are currently selected. If no items are selected, the list is empty.
void QCPLegend::reArrange | ( | ) |
If setAutoSize is true, the size needed to fit all legend contents is calculated and applied. Finally, the automatic positioning of the legend is performed, depending on the setPositionStyle setting.
bool QCPLegend::selectTestLegend | ( | const QPointF & | pos | ) | const |
Returns whether the point pos in pixels hits the legend rect.
QCPAbstractLegendItem * QCPLegend::selectTestItem | ( | const QPoint | pos | ) | const |
When the point pos in pixels hits a legend item, the item is returned. If no item is hit, 0 is returned.
void QCPLegend::selectionChanged | ( | QCPLegend::SelectableParts | selection | ) | [signal] |
This signal is emitted when the selection state of this legend has changed.
void QCPLegend::updateSelectionState | ( | ) | [protected, virtual] |
Updates the spItems part of the selection state of this legend by going through all child items and checking their selected state.
If no items are selected and the current selected state contains spItems, it is removed and the selectionChanged signal is emitted. If at least one item is selected and the current selection state does not contain spItems, it is added and the signal is emitted, too.
This function is called in the QCPAbstractLegendItem::setSelected functions to propagate their change to the parent legend.
bool QCPLegend::handleLegendSelection | ( | QMouseEvent * | event, |
bool | additiveSelection, | ||
bool & | modified | ||
) | [protected, virtual] |
Handles the selection event and returns true when the selection event hit any parts of the legend. If the selection state of any parts of the legend was changed, the output parameter modified is set to true.
When additiveSelecton is true, any new selections become selected in addition to the recent selections. The recent selections are not cleared. Further, clicking on one object multiple times in additive selection mode, toggles the selection of that object on and off.
To indicate that an event deselects the legend (i.e. the parts that are deselectable by the user, see setSelectable), pass 0 as event.
void QCPLegend::applyDefaultAntialiasingHint | ( | QCPPainter * | painter | ) | const [protected, virtual] |
A convenience function to easily set the QPainter::Antialiased hint on the provided painter before drawing main legend elements.
This is the antialiasing state the painter passed to the draw method is in by default.
This function takes into account the local setting of the antialiasing flag as well as the overrides set e.g. with QCustomPlot::setNotAntialiasedElements.
Implements QCPLayerable.
void QCPLegend::draw | ( | QCPPainter * | painter | ) | [protected, virtual] |
Draws the legend with the provided painter.
Implements QCPLayerable.
void QCPLegend::calculateAutoSize | ( | ) | [protected, virtual] |
Goes through similar steps as draw and calculates the width and height needed to fit all items and padding in the legend. The new calculated size is then applied to the mSize of this legend.
void QCPLegend::calculateAutoPosition | ( | ) | [protected, virtual] |
Sets the position dependant on the setPositionStyle setting and the margins.
QPen QCPLegend::getBorderPen | ( | ) | const [protected] |
Returns the pen used to paint the border of the legend, taking into account the selection state of the legend box.
QBrush QCPLegend::getBrush | ( | ) | const [protected] |
Returns the brush used to paint the background of the legend, taking into account the selection state of the legend box.
void QCPLayerable::setVisible | ( | bool | on | ) | [inherited] |
Sets the visibility of this layerable object. If an object is not visible, it will not be drawn on the QCustomPlot surface, and user interaction with it (e.g. click/selection) is not possible.
bool QCPLayerable::setLayer | ( | QCPLayer * | layer | ) | [inherited] |
Sets the layer of this layerable object. The object will be placed on top of the other objects already on layer.
Returns true on success, i.e. if layer is a valid layer.
bool QCPLayerable::setLayer | ( | const QString & | layerName | ) | [inherited] |
This is an overloaded function.
Sets the layer of this layerable object by name
Returns true on success, i.e. if layerName is a valid layer name.
void QCPLayerable::setAntialiased | ( | bool | enabled | ) | [inherited] |
Sets whether this object will be drawn antialiased or not.
Note that antialiasing settings may be overridden by QCustomPlot::setAntialiasedElements and QCustomPlot::setNotAntialiasedElements.
bool QCPLayerable::moveToLayer | ( | QCPLayer * | layer, |
bool | prepend | ||
) | [protected, inherited] |
Moves this layerable object to layer. If prepend is true, this object will be prepended to the new layer's list, i.e. it will be drawn below the objects already on the layer. If it is false, the object will be appended.
Returns true on success, i.e. if layer is a valid layer.
void QCPLayerable::applyAntialiasingHint | ( | QCPPainter * | painter, |
bool | localAntialiased, | ||
QCP::AntialiasedElement | overrideElement | ||
) | const [protected, inherited] |
Sets the QPainter::Antialiasing render hint on the provided painter, depending on the localAntialiased value as well as the overrides QCustomPlot::setAntialiasedElements and QCustomPlot::setNotAntialiasedElements. Which override enum this function takes into account is controlled via overrideElement.
QRect QCPLayerable::clipRect | ( | ) | const [protected, virtual, inherited] |
Returns the clipping rectangle of this layerable object. By default, this is the viewport of the parent QCustomPlot. Specific subclasses may reimplement this function to provide different clipping rects.
The returned clipping rect is set on the painter before the draw function of the respective object is called.
Reimplemented in QCPAbstractItem, and QCPAbstractPlottable.